Note:

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

Courses lists upgrade to 2.5: Difference between revisions

From MoodleDocs
m (Text replacement - "<code (.*)>" to "<syntaxhighlight lang="$1">")
(30 intermediate revisions by 4 users not shown)
Line 1: Line 1:
There are significant changes in course-related functions and UI in 2.5. This document is aimed to assist migration from 2.4 to 2.5. This is NOT a complete documentation on 2.5 features.
There are significant changes in course-related functions and UI in 2.5. This document is aimed to assist migration from 2.4 to 2.5. This is NOT a complete documentation on 2.5 features.
==Site administrators==
===Course management pages===
Pages that display lists of courses and course categories do not have editing mode any more: /course/index.php, /course/category.php, /course/search.php. Courses and categories can be managed on '''/course/manage.php'''. Switching editing mode on and off will not make changes. Although we tried to keep button to jump to manage page at the same place. '''Site Administration -> Courses -> Add/edit courses''' links to new management page as well.
If you have any blocks that are specific to any of the listed above pages, please '''check blocks configuration''' after upgrade. You can now configure block to appear on categories lists pages only or on any page inside category (including courses pages)
===Course summary files===
Course managers can now add summary files to the course. By default it is configured as up to one image but you can change the settings (see below). The images and/or links to the files will be displayed in the courses lists. To edit the files user needs the same capabilities as for changing the course summary (moodle/course:update AND moodle/course:changesummary)
===Administrative settings===
Some settings that changed their behaviour in Moodle 2.5:
'''Site Administration -> Appearence -> Courses'''
* Course contacts ($CFG->coursecontacts): Please note that only users enrolled in the course are shown as course contacts in Moodle 2.5
* Courses per page ($CFG->coursesperpage): This number now affects pagination for both subcategories and courses on course category page, limits the number of subcategories and/or courses in categories list or combo list on frontpage and pagination of course search results.
* Course summary files limit ($CFG->courseoverviewfileslimit): new setting - enjoy or set to 0 to disable
* Course summary files extensions ($CFG->courseoverviewfilesext): new setting
'''Site Administration -> Appearence -> Navigation'''
* Sort my courses ($CFG->navsortmycoursessort): Defines sorting criterion for enrolled courses both in navigation menu and 'My courses' list on frontpage. Hidden courses are shown in the end of the list (if user can see them).
'''Site Administration -> Front page -> Front page settings'''
(The following settings make no effect if your site has custom front page or front page is redirected to /my/)
* Front page ($CFG->frontpage): Note that there is a new option to display course search box. It is no longer displayed as part of any course or category listing
* Front page items when logged in ($CFG->frontpageloggedin): 'List of courses' shows available courses. If you want to show list of courses where user is enrolled to, use 'Enrolled courses'. But we recommend to use /my/ page instead. List of courses shows courses summary and is usually intededed to advertise a course. When student is already enrolled he/she is more interested in their progress in the course which is shown on /my/ page. $CFG->disablemycourses that could be set in config.php is ignored from now.
* Maximum category depth ($CFG->maxcategorydepth): this number affects both categories list and combo list. Do not set it high because now users are able to expand subcategories with Javascript sending AJAX requests to the server
'''Site Administration -> Server -> Performance'''
* $CFG->numcoursesincombo is removed from settings because it does not reflect the size of combo list. Site may have thousands of courses but only several top-level course categories. At the same time it may have 300 courses but combo list is configured to display them all. We trust site admins that they add combo list to the frontpage only when it is not huge and also configure $CFG->maxcategorydepth and $CFG->coursesperpage properly.
==Plugin developers==
The following functions are deprecated in Moodle 2.5. Their code is moved to /lib/deprecatedlib.php . The most of them are unlikely to be used outside of moodle core but if your plugin uses them please use new functions from coursecat class or functions from core_course_renderer.
<pre>
* Functions responsible for output in course/lib.php are deprecated, the code is moved to
  appropriate renderers: print_section(), print_section_add_menus(), get_print_section_cm_text(),
  make_editing_buttons()
  See functions' phpdocs in lib/deprecatedlib.php
* Function get_print_section_cm_text() is deprecated, replaced with methods in cm_info
* Functions responsible for managing and accessing course categories are moved to class coursecat
  in lib/coursecatlib.php, functions responsible for rendering courses and categories lists are
  moved to course/renderer.php. The following global functions are deprecated: make_categories_list(),
  category_delete_move(), category_delete_full(), move_category(), course_category_hide(),
  course_category_show(), get_course_category(), create_course_category(), get_all_subcategories(),
  get_child_categories(), get_categories(), print_my_moodle(), print_remote_course(),
  print_remote_host(), print_whole_category_list(), print_category_info(), get_course_category_tree(),
  print_courses(), print_course(), get_category_courses_array(), get_category_courses_array_recursively(),
  get_courses_wmanagers()
</pre>
To quickly check your code if it uses any of those functions you may run (this command will only check files in git repository):
<syntaxhighlight lang="php">
git grep -n -e '\bprint_section(' --or -e '\bprint_section_add_menus(' --or \( -e '[^:]\bmake_categories_list(' --and --not -e 'function make_categories_list\b' \) --or \( -e '[^:>]\bget_categories([^)]' --and --not -e 'function get_categories\b' \) --or -e '\bget_print_section_cm_text(' --or -e '\bmake_editing_buttons(' --or -e '\bcategory_delete_move(' --or -e '\bcategory_delete_full(' --or -e '\bmove_category(' --or -e '\bcourse_category_hide(' --or -e '\bcourse_category_show(' --or -e '\bget_course_category(' --or -e '\bcreate_course_category(' --or -e '\bget_all_subcategories(' --or -e '\bget_child_categories([^)]' --or -e '\bprint_my_moodle(' --or -e '\bprint_remote_course(' --or -e '\bprint_remote_host(' --or -e '\bprint_whole_category_list(' --or \( -e '[^>]\bprint_category_info(' --and --not -e 'function print_category_info\b' \) --or -e '\bget_course_category_tree(' --or -e '\bprint_courses(' --or -e '\bprint_course(' --or -e '\bget_category_courses_array(' --or -e '\bget_category_courses_array_recursively(' --or -e '\bget_courses_wmanagers(' -- '*.php' | grep -v '^lib/deprecatedlib.php'
</syntaxhighlight>
To check all files run from moodle root (very slow):
<syntaxhighlight lang="php">
grep -r --include=*.php -n -e '\bprint_section(' -e '\bprint_section_add_menus(' -e '[^:]\bmake_categories_list(' -e '[^:>]\bget_categories([^)]' -e '\bget_print_section_cm_text(' -e '\bmake_editing_buttons(' -e '\bcategory_delete_move(' -e '\bcategory_delete_full(' -e '\bmove_category(' -e '\bcourse_category_hide(' -e '\bcourse_category_show(' -e '\bget_course_category(' -e '\bcreate_course_category(' -e '\bget_all_subcategories(' -e '\bget_child_categories([^)]' -e '\bprint_my_moodle(' -e '\bprint_remote_course(' -e '\bprint_remote_host(' -e '\bprint_whole_category_list(' -e '[^>]\bprint_category_info(' -e '\bget_course_category_tree(' -e '\bprint_courses(' -e '\bprint_course(' -e '\bget_category_courses_array(' -e '\bget_category_courses_array_recursively(' -e '\bget_courses_wmanagers(' * | grep -v 'function make_categories_list(' | grep -v 'function print_category_info(' | grep -v 'function get_categories(' | grep -v 'lib/deprecatedlib.php'
</syntaxhighlight>


==Theme developers==
==Theme developers==
Line 5: Line 78:
All course listings are now performed through the same renderer functions.
All course listings are now performed through the same renderer functions.


There are significant changes to CSS classes used
There are significant changes to CSS classes used.
{| class="wikitable" width="100%"
|-
! valign="top" width="50%" | Moodle 2.4
! valign="top" width="50%" | Moodle 2.5
|-
| Go through your .css files in the themes and look for the following styles:
<syntaxhighlight lang="css">
.coursebox
.courseboxes /* not used any more, see .courses */
.course_category_tree
.categorylist /* not used any more */
table.category_subcategories /* may be used on course management pages */
.categorybox /* not used any more */
.categoryboxcontent /* not used any more */
#page-course-info
#page-course-enrol /* this is now #page-enrol-index */
#page-course-index
#page-course-category /* this is now #page-course-index-category */
#page-admin-course-category /* this is now #page-admin-course-manage */
#page-admin-course-index /* this is now #page-admin-course-manage */
</syntaxhighlight>
If you found any of those unfortunately you will need to do changes to your theme. Note that base and canvas themes provide all necessary classes and if the theme has one of them as parent it may not need overriding at all.
| valign="top" width="50%" | If you look for examples in Moodle 2.5 core themes search for styles containing:
<syntaxhighlight lang="css">
.coursebox
.course_category_tree
.courses
#page-course-info
#page-enrol-index
#page-course-index
#page-course-index-category
#page-admin-course-manage
</syntaxhighlight>
|}
 
Also if your theme overrides '''core_course_renderer::course_category_tree()''' or '''core_course_renderer::course_category_tree_category()''' you will also need to make changes.


===Pages that are affected by the new renderer functions===
===Pages that are affected by the new renderer functions===


To test your theme make sure that your site has several course categories with courses. Also some courses have summaries. Some courses should have enrollment methods other than manual (i.e. self enrollment). Some courses should have enrolled users with roles listed in $CFG->coursecontact. See screenshots attached to MDL-37009
To test your theme make sure that your site has several course categories with courses. Also some courses have summaries. Some courses should have enrollment methods other than manual (i.e. self enrollment). Some courses should have enrolled users with roles listed in $CFG->coursecontact. Add course summary files, both images and not images (you will need to change default settings to attach more than one file and/or non-image files). See screenshots attached to MDL-37009 and MDL-38708
 
You can test all screens in your theme using Behat tests: https://github.com/marinaglancy/moodle-tool_behatui
It requires some effort on installation but the result worths it.


Pages and responsible renderer functions:
Pages and responsible renderer functions:


* Courses lists on frontpage (see $CFG->frontpage, $CFG->frontpageloggedin) - '''core_course_renderer::courses_list_frontpage()'''
* Courses lists on frontpage (see $CFG->frontpage, $CFG->frontpageloggedin)
** List of courses where user is enrolled (please note, this is no longer recommended setting, use 'my' page instead!)
** List of courses where user is enrolled (please note, this is no longer recommended setting, use 'my' page instead!) - '''core_course_renderer::frontpage_my_courses()'''
** List of all available courses  
** List of all available courses - '''core_course_renderer::frontpage_available_courses()'''
** Categories list ($CFG->maxcategorydepth will affect how many subcategories levels to display)
** Categories list ($CFG->maxcategorydepth will affect how many subcategories levels to display) - '''core_course_renderer::frontpage_categories_list()'''
** Combo list ($CFG->maxcategorydepth will affect how many subcategories levels to display)
** Combo list ($CFG->maxcategorydepth will affect how many subcategories levels to display) - '''core_course_renderer::frontpage_combo_list()'''
* View courses (/course/index.php, /course/category.php) - '''core_course_renderer::course_category()'''
* View courses (/course/index.php, /course/category.php) - '''core_course_renderer::course_category()'''
** Category is empty
** Category is empty
Line 32: Line 144:
* Courses with tag - '''core_course_renderer::tagged_courses()'''
* Courses with tag - '''core_course_renderer::tagged_courses()'''
** Enable tag functionality, tag some courses with the same tag, add Tags block, click on tag name, the list of tagged courses is displayed (this is very similar to search results)
** Enable tag functionality, tag some courses with the same tag, add Tags block, click on tag name, the list of tagged courses is displayed (this is very similar to search results)
* Course information (.course-info-box) - '''core_course_renderer::course_info_box()'''
* Single course information box - '''core_course_renderer::course_info_box()'''
** If course has self enrollment, when student clicks on course name he is redirected to /enrol/index.php
** If course has self enrollment, when student clicks on course name he is redirected to /enrol/index.php
** In collapsed courses listing there is an "i" icon next to the course name, click on it, /course/info.php is opened
** In collapsed courses listing there is an "i" icon next to the course name, click on it, /course/info.php is opened
Line 42: Line 154:
====One course: core_course_renderer::coursecat_coursebox()====
====One course: core_course_renderer::coursecat_coursebox()====


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! How to use
! How to use
Line 50: Line 162:


To print information about one course on php page:
To print information about one course on php page:
<code php>
<syntaxhighlight lang="php">
$renderer = $PAGE->get_renderer('core', 'course');
$renderer = $PAGE->get_renderer('core', 'course');
echo $renderer->course_info_box($course);
echo $renderer->course_info_box($course);
</code>
</syntaxhighlight>
Function course_info_box() also existed in Moodle 2.4.
Function course_info_box() also existed in Moodle 2.4.


Remember that function print_course() is deprecated in 2.5.
Remember that function print_course() is deprecated in 2.5.
| valign="top" width="50%" | <code css>
| valign="top" width="50%" | <syntaxhighlight lang="css">
div.coursebox
div.coursebox
   div.info
   div.info
Line 66: Line 178:
   div.content
   div.content
     div.summary
     div.summary
    div.courseimage
        img
    div.coursefile
        a
     ul.teachers
     ul.teachers
         li
         li
     div.coursecat
     div.coursecat
         a[.dimmed]
         a[.dimmed]
</code>
</syntaxhighlight>
or
or
<code css>
<syntaxhighlight lang="css">
div.coursebox.collapsed
div.coursebox.collapsed
   div.info
   div.info
Line 80: Line 196:
     div.moreinfo /* contains link to /course/info.php or empty */
     div.moreinfo /* contains link to /course/info.php or empty */
   div.content
   div.content
</code>
</syntaxhighlight>
Also note that JS may be attached to switch between modes by hiding content or loading it via AJAX request. In this case the tag with class .name is not changing so the name does not change font size.
Also note that JS may be attached to switch between modes by hiding content or loading it via AJAX request. In this case the tag with class .name is not changing so the name does not change font size.
|}
|}
Line 86: Line 202:
====List of courses: core_course_renderer::coursecat_courses()====
====List of courses: core_course_renderer::coursecat_courses()====


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! How to use
! How to use
Line 94: Line 210:


To print custom list of courses on php page:
To print custom list of courses on php page:
<code php>
<syntaxhighlight lang="php">
$renderer = $PAGE->get_renderer('core', 'course');
$renderer = $PAGE->get_renderer('core', 'course');
echo $renderer->courses_list($courses);
echo $renderer->courses_list($courses);
</code>
</syntaxhighlight>
Remember that function print_courses() is deprecated.
Remember that function print_courses() is deprecated.
| valign="top" width="50%" | CSS classes
| valign="top" width="50%" | CSS classes
<code css>
<syntaxhighlight lang="css">
div.courses
div.courses
     div.paging /* pagination for courses */
     div.paging /* pagination for courses */
Line 108: Line 224:
     div.coursebox[.collapsed](.odd|.even).last
     div.coursebox[.collapsed](.odd|.even).last
     div.paging /* pagination for courses or 'more' link */
     div.paging /* pagination for courses or 'more' link */
</code>
</syntaxhighlight>
|}
|}


====List of subcategories: core_course_renderer::coursecat_subcategories()====
====List of subcategories: core_course_renderer::coursecat_subcategories()====


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! How to use
! How to use
Line 120: Line 236:
| valign="top" width="50%" | Can be used only as part of tree
| valign="top" width="50%" | Can be used only as part of tree
| valign="top" width="50%" | CSS classes
| valign="top" width="50%" | CSS classes
<code css>
<syntaxhighlight lang="css">
div.subcategories
div.subcategories
   div.paging /* pagination for categories */
   div.paging /* pagination for categories */
Line 136: Line 252:
   ...
   ...
   div.paging /* pagination for categories or 'more' link */
   div.paging /* pagination for categories or 'more' link */
</code>
</syntaxhighlight>
|}
|}


====Courses and categories tree: core_course_renderer::render_coursecat_renderable()====
====Courses and categories tree: core_course_renderer::coursecat_tree()====


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! How to use
! How to use
Line 149: Line 265:


Used in functions:
Used in functions:
<code php>
<syntaxhighlight lang="php">
$renderer = $PAGE->get_renderer('core', 'course');
$renderer = $PAGE->get_renderer('core', 'course');
echo $renderer->courses_list_frontpage($displaymode);
echo $renderer->courses_list_frontpage($displaymode);
Line 155: Line 271:
echo $renderer->tagged_courses($tagid);
echo $renderer->tagged_courses($tagid);
echo $renderer->course_category($id);
echo $renderer->course_category($id);
</code>
</syntaxhighlight>
| valign="top" width="50%" | <code css>
| valign="top" width="50%" | <syntaxhighlight lang="css">
div.course_category_tree /* plus extra class for each particular listing */
div.course_category_tree /* plus extra class for each particular listing */
     div.subcategories
     div.subcategories
Line 165: Line 281:
         div.addtoall.expandall
         div.addtoall.expandall
         div.removefromall.collapseall
         div.removefromall.collapseall
</code>
</syntaxhighlight>
|}
|}


Line 174: Line 290:
* /enrol/index.php (in Moodle 2.4 had url /course/enrol.php)
* /enrol/index.php (in Moodle 2.4 had url /course/enrol.php)


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! width="50%" | Moodle 2.4
! width="50%" | Moodle 2.4
! width="50%" | Moodle 2.5
! width="50%" | Moodle 2.5
|-
|-
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
h2.main /* course/info.php only */
h2.main /* course/info.php only */
   a /* link to course */
   a /* link to course */
Line 187: Line 303:
   ul.teachers
   ul.teachers
     li
     li
</code>
</syntaxhighlight>
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.box.generalbox.info
div.box.generalbox.info
   div.coursebox
   div.coursebox
Line 200: Line 316:
       ul.teachers
       ul.teachers
         li
         li
</code>
</syntaxhighlight>
|}
|}


Line 209: Line 325:
* category page where number of courses is less than $CFG->courseswithsummarieslimit
* category page where number of courses is less than $CFG->courseswithsummarieslimit


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! width="50%" style="text-align:center" | Moodle 2.4
! width="50%" style="text-align:center" | Moodle 2.4
! width="50%" style="text-align:center" | Moodle 2.5
! width="50%" style="text-align:center" | Moodle 2.5
|-
|-
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.box.courseboxes /* category view only */
div.box.courseboxes /* category view only */
   ul.unlist /* category view and frontpage */
   ul.unlist /* category view and frontpage */
Line 230: Line 346:
           div.enrolmenticons
           div.enrolmenticons
             img
             img
</code>
</syntaxhighlight>
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.courses
div.courses
   div.paging /* pagination for courses */
   div.paging /* pagination for courses */
Line 242: Line 358:
     div.content
     div.content
       div.summary
       div.summary
      div.courseimage
      div.coursefile
       ul.teachers
       ul.teachers
         li
         li
Line 250: Line 368:
   div.coursebox(.odd|.even).last
   div.coursebox(.odd|.even).last
   div.paging /* pagination for courses or 'more' link */
   div.paging /* pagination for courses or 'more' link */
</code>
</syntaxhighlight>
|-
|-
! colspan="2" style="text-align:center" | CSS directives replacements
! colspan="2" style="text-align:center" | CSS directives replacements
Line 271: Line 389:


====Combo list on frontpage====
====Combo list on frontpage====
{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! width="50%" style="text-align:center" | Moodle 2.4
! width="50%" style="text-align:center" | Moodle 2.4
! width="50%" style="text-align:center" | Moodle 2.5
! width="50%" style="text-align:center" | Moodle 2.5
|-
|-
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.course_category_tree
div.course_category_tree
   div.category[.with_children] /* in some themes has background image with gradient */
   div.category[.with_children] /* in some themes has background image with gradient */
Line 291: Line 409:
           img, a img /* enrolment icons and link to /course/info.php */
           img, a img /* enrolment icons and link to /course/info.php */
       ... /* more div.course */
       ... /* more div.course */
</code>
</syntaxhighlight>
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.course_category_tree.frontpage-category-combo
div.course_category_tree.frontpage-category-combo
   div.subcategories
   div.subcategories
Line 319: Line 437:
     div.addtoall.expandall
     div.addtoall.expandall
     div.removefromall.collapseall
     div.removefromall.collapseall
</code>
</syntaxhighlight>
|-
|-
! colspan="2" style="text-align:center" | CSS directives replacements
! colspan="2" style="text-align:center" | CSS directives replacements
Line 348: Line 466:
====Categories lists====
====Categories lists====


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! style="text-align:center" width="50%" | Moodle 2.4
! style="text-align:center" width="50%" | Moodle 2.4
Line 354: Line 472:
|-
|-
| valign="top" | Categories list on the frontpage
| valign="top" | Categories list on the frontpage
<code css>
<syntaxhighlight lang="css">
div.box.generalbox.categorybox
div.box.generalbox.categorybox
   div.categorylist
   div.categorylist
Line 364: Line 482:
         a
         a
         span.numberofcourse
         span.numberofcourse
</code>
</syntaxhighlight>
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.course_category_tree.frontpage-category-names
div.course_category_tree.frontpage-category-names
   div.subcategories
   div.subcategories
Line 381: Line 499:
     div.addtoall.expandall
     div.addtoall.expandall
     div.removefromall.collapseall
     div.removefromall.collapseall
</code>
</syntaxhighlight>
|-
|-
| valign="top" | Categories list on /course/index.php
| valign="top" | Categories list on /course/index.php
<code css>
<syntaxhighlight lang="css">
div.box.categorybox
div.box.categorybox
   div.categorylist
   div.categorylist
Line 415: Line 533:
     ... /* other courses */
     ... /* other courses */
   ... /* other categories */
   ... /* other categories */
</code>
</syntaxhighlight>
| valign="top" | <code css>
| valign="top" | <syntaxhighlight lang="css">
div.course_category_tree.category-browse.category-browse-0
div.course_category_tree.category-browse.category-browse-0
   div.subcategories
   div.subcategories
Line 441: Line 559:
     div.addtoall.expandall
     div.addtoall.expandall
     div.removefromall.collapseall
     div.removefromall.collapseall
</code>
</syntaxhighlight>
Note that by default categories content is not loaded, it may be loaded by AJAX request
Note that by default categories content is not loaded, it may be loaded by AJAX request
|-
|-
Line 464: Line 582:
====Browsing category====
====Browsing category====


{| class="nicetable" width="100%"
{| class="wikitable" width="100%"
|-
|-
! width="50%" style="text-align:center" | Moodle 2.4
! width="50%" style="text-align:center" | Moodle 2.4
Line 471: Line 589:
|-
|-
| '''Category view with subcategories'''
| '''Category view with subcategories'''
<code css>
<syntaxhighlight lang="css">
table.generalbox.boxaligncenter.category_subcategories
table.generalbox.boxaligncenter.category_subcategories
   thead
   thead
Line 499: Line 617:
       div.coursebox
       div.coursebox
       ...
       ...
</code>
</syntaxhighlight>
| rowspan="2" | <code css>
| rowspan="2" | <syntaxhighlight lang="css">
div.course_category_tree.category-browse
div.course_category_tree.category-browse
   div.subcategories
   div.subcategories
Line 525: Line 643:
       div.content
       div.content
         div.summary
         div.summary
        div.courseimage
        div.coursefile
         ul.teachers
         ul.teachers
           li
           li
Line 532: Line 652:
     div.addtoall.expandall
     div.addtoall.expandall
     div.removefromall.collapseall
     div.removefromall.collapseall
</code>
</syntaxhighlight>
Note that by default subcategory content is not loaded, it may be loaded by AJAX request
Note that by default subcategory content is not loaded, it may be loaded by AJAX request


Line 539: Line 659:
| '''Category view with paginated courses'''
| '''Category view with paginated courses'''
or category with more than $CFG->courseswithsummarieslimit courses
or category with more than $CFG->courseswithsummarieslimit courses
<code css>
<syntaxhighlight lang="css">
table.generalbox.boxaligncenter.category_subcategories
table.generalbox.boxaligncenter.category_subcategories
   ... /* see above */
   ... /* see above */
Line 555: Line 675:
     tr
     tr
     ...
     ...
</code>
</syntaxhighlight>
|-
|-
! colspan="2" style="text-align:center" | CSS directives replacements
! colspan="2" style="text-align:center" | CSS directives replacements

Revision as of 08:13, 15 July 2021

There are significant changes in course-related functions and UI in 2.5. This document is aimed to assist migration from 2.4 to 2.5. This is NOT a complete documentation on 2.5 features.

Site administrators

Course management pages

Pages that display lists of courses and course categories do not have editing mode any more: /course/index.php, /course/category.php, /course/search.php. Courses and categories can be managed on /course/manage.php. Switching editing mode on and off will not make changes. Although we tried to keep button to jump to manage page at the same place. Site Administration -> Courses -> Add/edit courses links to new management page as well.

If you have any blocks that are specific to any of the listed above pages, please check blocks configuration after upgrade. You can now configure block to appear on categories lists pages only or on any page inside category (including courses pages)

Course summary files

Course managers can now add summary files to the course. By default it is configured as up to one image but you can change the settings (see below). The images and/or links to the files will be displayed in the courses lists. To edit the files user needs the same capabilities as for changing the course summary (moodle/course:update AND moodle/course:changesummary)

Administrative settings

Some settings that changed their behaviour in Moodle 2.5:

Site Administration -> Appearence -> Courses

  • Course contacts ($CFG->coursecontacts): Please note that only users enrolled in the course are shown as course contacts in Moodle 2.5
  • Courses per page ($CFG->coursesperpage): This number now affects pagination for both subcategories and courses on course category page, limits the number of subcategories and/or courses in categories list or combo list on frontpage and pagination of course search results.
  • Course summary files limit ($CFG->courseoverviewfileslimit): new setting - enjoy or set to 0 to disable
  • Course summary files extensions ($CFG->courseoverviewfilesext): new setting

Site Administration -> Appearence -> Navigation

  • Sort my courses ($CFG->navsortmycoursessort): Defines sorting criterion for enrolled courses both in navigation menu and 'My courses' list on frontpage. Hidden courses are shown in the end of the list (if user can see them).

Site Administration -> Front page -> Front page settings

(The following settings make no effect if your site has custom front page or front page is redirected to /my/)

  • Front page ($CFG->frontpage): Note that there is a new option to display course search box. It is no longer displayed as part of any course or category listing
  • Front page items when logged in ($CFG->frontpageloggedin): 'List of courses' shows available courses. If you want to show list of courses where user is enrolled to, use 'Enrolled courses'. But we recommend to use /my/ page instead. List of courses shows courses summary and is usually intededed to advertise a course. When student is already enrolled he/she is more interested in their progress in the course which is shown on /my/ page. $CFG->disablemycourses that could be set in config.php is ignored from now.
  • Maximum category depth ($CFG->maxcategorydepth): this number affects both categories list and combo list. Do not set it high because now users are able to expand subcategories with Javascript sending AJAX requests to the server

Site Administration -> Server -> Performance

  • $CFG->numcoursesincombo is removed from settings because it does not reflect the size of combo list. Site may have thousands of courses but only several top-level course categories. At the same time it may have 300 courses but combo list is configured to display them all. We trust site admins that they add combo list to the frontpage only when it is not huge and also configure $CFG->maxcategorydepth and $CFG->coursesperpage properly.


Plugin developers

The following functions are deprecated in Moodle 2.5. Their code is moved to /lib/deprecatedlib.php . The most of them are unlikely to be used outside of moodle core but if your plugin uses them please use new functions from coursecat class or functions from core_course_renderer.

* Functions responsible for output in course/lib.php are deprecated, the code is moved to
  appropriate renderers: print_section(), print_section_add_menus(), get_print_section_cm_text(),
  make_editing_buttons()
  See functions' phpdocs in lib/deprecatedlib.php
* Function get_print_section_cm_text() is deprecated, replaced with methods in cm_info
* Functions responsible for managing and accessing course categories are moved to class coursecat
  in lib/coursecatlib.php, functions responsible for rendering courses and categories lists are
  moved to course/renderer.php. The following global functions are deprecated: make_categories_list(),
  category_delete_move(), category_delete_full(), move_category(), course_category_hide(),
  course_category_show(), get_course_category(), create_course_category(), get_all_subcategories(),
  get_child_categories(), get_categories(), print_my_moodle(), print_remote_course(),
  print_remote_host(), print_whole_category_list(), print_category_info(), get_course_category_tree(),
  print_courses(), print_course(), get_category_courses_array(), get_category_courses_array_recursively(),
  get_courses_wmanagers()

To quickly check your code if it uses any of those functions you may run (this command will only check files in git repository):

git grep -n -e '\bprint_section(' --or -e '\bprint_section_add_menus(' --or \( -e '[^:]\bmake_categories_list(' --and --not -e 'function make_categories_list\b' \) --or \( -e '[^:>]\bget_categories([^)]' --and --not -e 'function get_categories\b' \) --or -e '\bget_print_section_cm_text(' --or -e '\bmake_editing_buttons(' --or -e '\bcategory_delete_move(' --or -e '\bcategory_delete_full(' --or -e '\bmove_category(' --or -e '\bcourse_category_hide(' --or -e '\bcourse_category_show(' --or -e '\bget_course_category(' --or -e '\bcreate_course_category(' --or -e '\bget_all_subcategories(' --or -e '\bget_child_categories([^)]' --or -e '\bprint_my_moodle(' --or -e '\bprint_remote_course(' --or -e '\bprint_remote_host(' --or -e '\bprint_whole_category_list(' --or \( -e '[^>]\bprint_category_info(' --and --not -e 'function print_category_info\b' \) --or -e '\bget_course_category_tree(' --or -e '\bprint_courses(' --or -e '\bprint_course(' --or -e '\bget_category_courses_array(' --or -e '\bget_category_courses_array_recursively(' --or -e '\bget_courses_wmanagers(' -- '*.php' | grep -v '^lib/deprecatedlib.php'

To check all files run from moodle root (very slow):

grep -r --include=*.php -n -e '\bprint_section(' -e '\bprint_section_add_menus(' -e '[^:]\bmake_categories_list(' -e '[^:>]\bget_categories([^)]' -e '\bget_print_section_cm_text(' -e '\bmake_editing_buttons(' -e '\bcategory_delete_move(' -e '\bcategory_delete_full(' -e '\bmove_category(' -e '\bcourse_category_hide(' -e '\bcourse_category_show(' -e '\bget_course_category(' -e '\bcreate_course_category(' -e '\bget_all_subcategories(' -e '\bget_child_categories([^)]' -e '\bprint_my_moodle(' -e '\bprint_remote_course(' -e '\bprint_remote_host(' -e '\bprint_whole_category_list(' -e '[^>]\bprint_category_info(' -e '\bget_course_category_tree(' -e '\bprint_courses(' -e '\bprint_course(' -e '\bget_category_courses_array(' -e '\bget_category_courses_array_recursively(' -e '\bget_courses_wmanagers(' * | grep -v 'function make_categories_list(' | grep -v 'function print_category_info(' | grep -v 'function get_categories(' | grep -v 'lib/deprecatedlib.php'

Theme developers

All course listings are now performed through the same renderer functions.

There are significant changes to CSS classes used.

Moodle 2.4 Moodle 2.5
Go through your .css files in the themes and look for the following styles:
.coursebox
.courseboxes /* not used any more, see .courses */
.course_category_tree
.categorylist /* not used any more */
table.category_subcategories /* may be used on course management pages */
.categorybox /* not used any more */
.categoryboxcontent /* not used any more */
#page-course-info
#page-course-enrol /* this is now #page-enrol-index */
#page-course-index
#page-course-category /* this is now #page-course-index-category */
#page-admin-course-category /* this is now #page-admin-course-manage */
#page-admin-course-index /* this is now #page-admin-course-manage */

If you found any of those unfortunately you will need to do changes to your theme. Note that base and canvas themes provide all necessary classes and if the theme has one of them as parent it may not need overriding at all.

If you look for examples in Moodle 2.5 core themes search for styles containing:
.coursebox
.course_category_tree
.courses
#page-course-info
#page-enrol-index
#page-course-index
#page-course-index-category
#page-admin-course-manage

Also if your theme overrides core_course_renderer::course_category_tree() or core_course_renderer::course_category_tree_category() you will also need to make changes.

Pages that are affected by the new renderer functions

To test your theme make sure that your site has several course categories with courses. Also some courses have summaries. Some courses should have enrollment methods other than manual (i.e. self enrollment). Some courses should have enrolled users with roles listed in $CFG->coursecontact. Add course summary files, both images and not images (you will need to change default settings to attach more than one file and/or non-image files). See screenshots attached to MDL-37009 and MDL-38708

You can test all screens in your theme using Behat tests: https://github.com/marinaglancy/moodle-tool_behatui It requires some effort on installation but the result worths it.

Pages and responsible renderer functions:

  • Courses lists on frontpage (see $CFG->frontpage, $CFG->frontpageloggedin)
    • List of courses where user is enrolled (please note, this is no longer recommended setting, use 'my' page instead!) - core_course_renderer::frontpage_my_courses()
    • List of all available courses - core_course_renderer::frontpage_available_courses()
    • Categories list ($CFG->maxcategorydepth will affect how many subcategories levels to display) - core_course_renderer::frontpage_categories_list()
    • Combo list ($CFG->maxcategorydepth will affect how many subcategories levels to display) - core_course_renderer::frontpage_combo_list()
  • View courses (/course/index.php, /course/category.php) - core_course_renderer::course_category()
    • Category is empty
    • Category has only subcategories
    • Category has only subcategories and there are more than $CFG->coursesperpage of them
    • Category has only courses and there are less courses than $CFG->courseswithsummarieslimit
    • Category has only courses and there are more than $CFG->courseswithsummarieslimit but less than $CFG->coursesperpage
    • Category has only courses and there are more than $CFG->coursesperpage
    • Category has both courses and categories and at least one of the lists is bigger than $CFG->coursesperpage (make sure to click "more" link for both courses and categories list).
  • Search courses - core_course_renderer::search_courses()
    • No courses found
    • Less than $CFG->coursesperpage courses found
    • More than $CFG->coursesperpage courses found
  • Courses with tag - core_course_renderer::tagged_courses()
    • Enable tag functionality, tag some courses with the same tag, add Tags block, click on tag name, the list of tagged courses is displayed (this is very similar to search results)
  • Single course information box - core_course_renderer::course_info_box()
    • If course has self enrollment, when student clicks on course name he is redirected to /enrol/index.php
    • In collapsed courses listing there is an "i" icon next to the course name, click on it, /course/info.php is opened

Hint. To change $CFG->xxx type xxx in the search box in Administration block.

New renderer functions

One course: core_course_renderer::coursecat_coursebox()

How to use What you get (HTML/CSS)
This function is used to render courses lists, print course information and/or display courses and categories trees in many places.

To print information about one course on php page:

$renderer = $PAGE->get_renderer('core', 'course');
echo $renderer->course_info_box($course);

Function course_info_box() also existed in Moodle 2.4.

Remember that function print_course() is deprecated in 2.5.

div.coursebox
  div.info
    h3.name
        a[.dimmed]
    div.enrolmenticons
    div.moreinfo /* empty, may be populated with JS */
  div.content
    div.summary
    div.courseimage
        img
    div.coursefile
        a
    ul.teachers
        li
    div.coursecat
        a[.dimmed]

or

div.coursebox.collapsed
  div.info
    div.name /* Note that it is not <h3> any more */
        a
    div.enrolmenticons
    div.moreinfo /* contains link to /course/info.php or empty */
  div.content

Also note that JS may be attached to switch between modes by hiding content or loading it via AJAX request. In this case the tag with class .name is not changing so the name does not change font size.

List of courses: core_course_renderer::coursecat_courses()

How to use What you get (HTML/CSS)
Also is already used in many course listings.

To print custom list of courses on php page:

$renderer = $PAGE->get_renderer('core', 'course');
echo $renderer->courses_list($courses);

Remember that function print_courses() is deprecated.

CSS classes
div.courses
    div.paging /* pagination for courses */
    div.coursebox[.collapsed].odd.first
    div.coursebox[.collapsed].even
    ...
    div.coursebox[.collapsed](.odd|.even).last
    div.paging /* pagination for courses or 'more' link */

List of subcategories: core_course_renderer::coursecat_subcategories()

How to use What you get (HTML/CSS)
Can be used only as part of tree CSS classes
div.subcategories
  div.paging /* pagination for categories */
  div.category[.with_children[.collapsed]][.loaded|.notloaded][.dimmed_category]
    div.info
      [h3|h4].name /* <h4> for nested categories */
        a
    div.content /* always present even if empty */
      div.subcategories
        .... /* recursive */
      div.courses
        ... /* see above */
  div.category
  div.category
  ...
  div.paging /* pagination for categories or 'more' link */

Courses and categories tree: core_course_renderer::coursecat_tree()

How to use What you get (HTML/CSS)
Can be called as $renderer->render($coursecat) but since the class coursecat_renderable is defined inside /course/renderer.php it is not recommended to use it from outside of the class.

Used in functions:

$renderer = $PAGE->get_renderer('core', 'course');
echo $renderer->courses_list_frontpage($displaymode);
echo $renderer->search_courses($searchcriteria);
echo $renderer->tagged_courses($tagid);
echo $renderer->course_category($id);
div.course_category_tree /* plus extra class for each particular listing */
    div.subcategories
        ... /* see above */
    div.courses
        ... /* see above */
    div.controls
        div.addtoall.expandall
        div.removefromall.collapseall

Changes in CSS

Pages, displaying information about one course only

  • /course/info.php
  • /enrol/index.php (in Moodle 2.4 had url /course/enrol.php)
Moodle 2.4 Moodle 2.5
h2.main /* course/info.php only */
  a /* link to course */
  br /* plus short course name in parenthesis */
div.box.generalbox.info
  div.no-overflow /* missing if there is no summary */
  ul.teachers
    li
div.box.generalbox.info
  div.coursebox
    div.info
      h3.name
        a[.dimmed]
      div.enrolmenticons
      div.moreinfo /* empty */
    div.content
      div.summary
      ul.teachers
        li

Courses lists

  • search results
  • tagged courses
  • list of enrolled or available courses on the front page
  • category page where number of courses is less than $CFG->courseswithsummarieslimit
Moodle 2.4 Moodle 2.5
div.box.courseboxes /* category view only */
  ul.unlist /* category view and frontpage */
    li /* category view and frontpage */
      div.coursebox
        div.info
          h3.name
            a
          ul.teachers
            li
        div.summary
          div.no-overflow
             ...
             p.category /* search results only */
          div.enrolmenticons
             img
div.courses
  div.paging /* pagination for courses */
  div.coursebox.odd.first
    div.info
      h3.name
        a[.dimmed]
      div.enrolmenticons
      div.moreinfo /* empty, maybe populated with JS */
    div.content
      div.summary
      div.courseimage
      div.coursefile
      ul.teachers
        li
      div.coursecat
        a[.dimmed]
  div.coursebox.even
  ...
  div.coursebox(.odd|.even).last
  div.paging /* pagination for courses or 'more' link */
CSS directives replacements
Moodle 2.4 Moodle 2.5
.coursebox > .info > ul.teachers > li .coursebox > .content > ul.teachers > li
.coursebox > .summary .coursebox > .content > .summary
.coursebox > .summary > p.category .coursebox > .content > div.coursecat (could not use word 'category' any more because it might cause CSS confusions)
.coursebox > .summary > .enrolmenticons .coursebox > .info > .enrolmenticons

Combo list on frontpage

Moodle 2.4 Moodle 2.5
div.course_category_tree
  div.category[.with_children] /* in some themes has background image with gradient */
    div.category_label /* has background image 'collapsed'/'expanded' */
      a.category_link    
    div.subcategories
      div.category
        ... /* recursive */
      ... /* more div.category */
    div.courses
      div.course
        a.course_link
        div.course_info
           img, a img /* enrolment icons and link to /course/info.php */
      ... /* more div.course */
div.course_category_tree.frontpage-category-combo
  div.subcategories
    div.category[.with_children[.collapsed]][.loaded|.notloaded][.dimmed_category]
      div.info
        [h3|h4].name /* <h4> for nested categories */
          a
      div.content
        div.subcategories
          .... /* recursive */
        div.courses
          ... /* see in the same example below */
    ... /* more div.category */
    div.paging.paging-viewmore /* 'more' link for categories */
  div.courses
    div.coursebox.collapsed(.odd|.even)[.first][.last]
      div.info
        div.name /* Note that it is not <h3> any more */
          a[.dimmed]
        div.enrolmenticons
        div.moreinfo /* contains link to /course/info.php or empty */
      div.content /* empty, placeholder for JS */
    ... /* more div.coursebox */
    div.paging.paging-viewmore /* 'more' link for courses */
  div.controls
    div.addtoall.expandall
    div.removefromall.collapseall
CSS directives replacements
Moodle 2.4 Moodle 2.5
.course_category_tree .courses. > .course .course_category_tree .courses. > .coursebox (or .coursebox.collapsed)
.course_category_tree .courses. > .course > .course-info .course_category_tree .courses. > .coursebox > .info > .enrolmenticons,

.course_category_tree .courses. > .coursebox > .moreinfo

.course_category_tree .courses. > .course > .course_link .course_category_tree .courses. > .coursebox > .info > .name > a
.course_category_tree .category > .category_label > .category_link .course_category_tree .category > .info > .name > a
.course_category_tree .category > .subcategories .course_category_tree .category > .content > .subcategories
.course_category_tree .category > .courses .course_category_tree .category > .content > .courses

Categories lists

Moodle 2.4 Moodle 2.5
Categories list on the frontpage
div.box.generalbox.categorybox
  div.categorylist
    div.category
      a
      span.numberofcourse
    div.category
      div.indentation /* maybe several nested */
        a
        span.numberofcourse
div.course_category_tree.frontpage-category-names
  div.subcategories
    div.category[.with_children[.collapsed]][.loaded|.notloaded][.dimmed_category]
      div.info
        [h3|h4].name /* <h4> for nested categories */
          a
          span.numberofcourse
      div.content
        div.subcategories
          .... /* recursive */
    ... /* more div.category */
    div.paging.paging-viewmore /* 'more' link */
  div.controls
    div.addtoall.expandall
    div.removefromall.collapseall
Categories list on /course/index.php
div.box.categorybox
  div.categorylist
    div.category
      div.image
        img /* 'i/course' */
      div.name
        a
    div.clearfloat /* empty */
    div.course /* note that it is not nested in .category */
      div.indentation
        div.name
          img /* enrolment icon */
          a /* link to course */
        div.info
          a /* link to /course/info.php */
            img
    div.course
    ... /* other courses */
  div.categorylist
    div.category
      div.indentation /* indicates that this category is nested */
        div.image
        div.name
    div.course
      div.indentation
        div.indentation
          div.name
          div.info
    ... /* other courses */
  ... /* other categories */
div.course_category_tree.category-browse.category-browse-0
  div.subcategories
    div.category[.with_children[.collapsed]][.loaded|.notloaded][.dimmed_category]
      div.info
        [h3|h4].name /* <h4> for nested categories */
          a
      div.content
        div.subcategories
          .... /* recursive */
        div.courses
          div.coursebox.collapsed(.odd|.even)[.first][.last]
            div.info
              div.name
                a[.dimmed]
              div.enrolmenticons
              div.moreinfo /* contains link to /course/info.php or empty */
            div.content /* empty */
          ... /* more div.coursebox */
          div.paging.paging-viewmore /* 'more' link for courses */
    ... /* more div.category */
    div.paging.paging-viewmore /* 'more' link for categories */
  div.controls
    div.addtoall.expandall
    div.removefromall.collapseall

Note that by default categories content is not loaded, it may be loaded by AJAX request

CSS directives replacements
Moodle 2.4 Moodle 2.5
.categorylist > .category div.name > a .course_category_tree .subcategories > .category > div.info > .name > a (Note that now courses are nested inside category and if directive just say .category .name it will also be applied to names of the courses inside category!)
.categorylist > .category .image does not exist anymore, if you want to add an icon for category add it as background for .category > .info > .name > a
.categorylist .indentation does not exist anymore, all subcategories and courses are nested div's now
.categorylist .course .course_category_tree .courses. > .coursebox

Browsing category

Moodle 2.4 Moodle 2.5
Category view with subcategories
table.generalbox.boxaligncenter.category_subcategories
  thead
    tr
      th /* 'Sub-categories' */
  tbody
    tr
      td
        a
    tr
    ...
div.box.courseboxes
  ul.unlist
    li
      div.coursebox
        div.info
          h3.name
            a
          ul.teachers
            li
        div.summary
          div.no-overflow
             ...
             p.category /* search results only */
          div.enrolmenticons
             img
      div.coursebox
      ...
div.course_category_tree.category-browse
  div.subcategories
    div.paging /* pagination for categories */
    div.category[.with_children[.collapsed]][.loaded|.notloaded][.dimmed_category]
      div.info
        [h3|h4].name /* <h4> for nested categories */
          a
      div.content
        div.subcategories
          .... /* recursive */
        div.courses
          ... /* see in the same example below */
    ... /* more div.category */
    div.paging /* pagination for categories or 'more' link */
  div.courses
    div.paging /* pagination for courses */
    div.coursebox[.collapsed](.odd|.even)[.first][.last]
      div.info
        (h3|div).name
          a[.dimmed]
        div.enrolmenticons
        div.moreinfo /* contains link to /course/info.php or empty */
      div.content
        div.summary
        div.courseimage
        div.coursefile
        ul.teachers
          li
    ... /* more div.coursebox */
    div.paging /* pagination for courses or 'more' link */
  div.controls
    div.addtoall.expandall
    div.removefromall.collapseall

Note that by default subcategory content is not loaded, it may be loaded by AJAX request

If there are more than $CFG->courseswithsummarieslimit courses in category they will be displayed as div.coursebox.collapsed (with empty .content)

Category view with paginated courses

or category with more than $CFG->courseswithsummarieslimit courses

table.generalbox.boxaligncenter.category_subcategories
  ... /* see above */
div.paging /* applies to courses only! */
table.generalbox.boxaligncenter
  tbody
    tr
      th /* 'Courses' */
      th /* empty */
    tr
      td
        a /* link to course */
      td
        img, a img /* enrolment icons and link to /course/info.php */
    tr
    ...
CSS directives replacements
Moodle 2.4 Moodle 2.5
.courseboxes .course_category_tree.category-browse
table.category_subcategories .course_category_tree .subcategories (no more tables!)
also see styles for Listings of courses