Course formats: Collapsed Topics

format_topcoll
Maintained by Gareth J BarnardGareth J Barnard
An interchangeable topic or week based format that solves the issue of the 'Scroll of Death' when a course has many topics.

Collapsed Topics 2.4.4

Release notes

Introduction
============
Topic based course format with an individual 'toggle' for each topic except 0.

If you find an issue with the format, please see the 'Reporting Issues' section below.

Required version of Moodle
==========================
This version works with Moodle version 2012120301.02 release 2.4.1+ (Build: 20130118) and above until the next release.

Download and documentation
==========================
The primary source for downloading this branch of the format is https://moodle.org/plugins/view.php?plugin=format_topcoll
with 'Select Moodle version:' set at 'Moodle 2.4'.

The secondary source is a tagged version with the v2.4 prefix on https://github.com/gjb2048/moodle-format_topcoll/tags

If you download from the development area - https://github.com/gjb2048/moodle-format_topcoll/tree/MOODLE_24 - consider that
the code is unstable and not for use in production environments. This is because I develop the next version in stages
and use GitHub as a means of backup. Therefore the code is not finished, subject to alteration and requires testing.

Documented on http://docs.moodle.org/24/en/Collapsed_Topics_course_format

Supporting Collapsed Topics development
=======================================
If you find Collapsed Topics useful and beneficial, please consider donating to its development through the following
PayPal link:

[PayPal donate](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=6KEALTXATCXVE)

I develop and maintain for free and any donations to assist me in this endeavour are appreciated.

Previous versions and required version of Moodle
================================================
If this version does not work with your version of Moodle because it requires a newer version of Moodle, then
please download an older version from https://moodle.org/plugins/pluginversions.php?plugin=format_topcoll using
this table as a guide:

CT version - Moodle version
V2.4.2 2.4.1+, version 2012120301.02 (Build: 20130118).
V2.4.1.7 2.4+ version 2012120300.00 (Build: 20121203).

New features for this Moodle 2.4.1 version
==========================================
1. Settings moved to the 'Edit course settings' form.
2. Ability to turn off persistence by changing the default 'defaulttogglepersistence' in
'Site Administration -> Plugins -> Course formats -> Collapsed Topics'.
3. Horizontal and vertical column layouts.
4. Left, centre and right toggle text alignment.
5. Icon sets where you can choose what set of control icons are appropriate on a per course basis. See 'Icon Sets'
below.
6. Moved all 'tcconfig.php' default functionalty to 'Site Administration -> Plugins -> Course formats -> Collapsed Topics'
so that defaults can be changed by the administrator from within Moodle without resorting to code changes.
7. Added capabilities 'format/topcoll:changelayout', 'format/topcoll:changecolour', 'format/topcoll:changetogglealignment'
and 'format/topcoll:changetoggleiconset' to editing teachers and managers such that site administrators can choose to
disable functionality through roles if they wish.

Installation
============
1. Ensure you have the version of Moodle as stated above in 'Required version of Moodle'. This is essential as the
format relies on underlying core code that is out of my control.
2. If upgrading from Moodle 1.9, 2.0 or 2.1, please see 'Upgrading from Moodle 1.9, 2.0 or 2.1' below.
3. If upgrading from Moodle 2.2, please see 'Upgrading from Moodle 2.2' below.
4. If upgrading from Moodle 2.3, please see 'Upgrade Instructions' below.
5. Put Moodle in 'Maintenance Mode' (docs.moodle.org/en/admin/setting/maintenancemode) so that there are no
users using it bar you as the administrator - if you have not already done so.
6. Copy 'topcoll' to '/course/format/' if you have not already done so.
7. In 'Site Administration -> Plugins -> Course formats -> Collapsed Topics' change the values of 'defaultlayoutelement',
'defaultlayoutstructure' and 'defaultlayoutcolumns' for setting the default layout, structure and columns respectively
for new / updating courses as desired by following the instructions contained within.
8. In 'Site Administration -> Plugins -> Course formats -> Collapsed Topics' change the values of 'defaulttgfgcolour',
'defaulttgbgcolour' and 'defaulttgbghvrcolour' for setting the default toggle colours.
9. In 'Site Administration -> Plugins -> Course formats -> Collapsed Topics' turn off toggle persistence if desired by
changing 'defaulttogglepersistence' as indicated.
10. In 'Site Administration -> Plugins -> Course formats -> Collapsed Topics' set the default toggle alignment by changing
'defaulttogglealignment' as indicated.
11. Login as an administrator and follow standard the 'plugin' update notification. If needed, go to
'Site administration' -> 'Notifications' if this does not happen.
12. To change the arrow graphic please see 'Icon Sets' below.
13. Put Moodle out of Maintenance Mode.

Upgrade Instructions
====================
1. Ensure you have the version of Moodle as stated above in 'Required version of Moodle'. This is essential as the
format relies on underlying core code that is out of my control.
2. If upgrading from Moodle 1.9, 2.0, 2.1 or 2.2 please read the appropriate sections below.
3. Put Moodle in 'Maintenance Mode' so that there are no users using it bar you as the administrator.
4. In '/course/format/' move old 'topcoll' directory to a backup folder outside of Moodle.
5. Follow installation instructions above.
6. Perform a 'Purge all caches' under 'Home -> Site administration -> Development -> Purge all caches'.
7. Put Moodle out of Maintenance Mode.

Upgrading from Moodle 1.9, 2.0 or 2.1
-------------------------------------
Moodle 2.4 requires that Moodle 2.2 is installed to upgrade from, so therefore Moodle 2.2 is an intermediate step.
So:
1. Put Moodle in 'Maintenance Mode' so that there are no users using it bar you as the administrator.
2. In '/course/format/' move old 'topcoll' directory to a backup folder outside of Moodle.
3. Do not copy in the new version of 'topcoll' yet! As this will cause the upgrade to fail.
4. Upgrade to Moodle 2.2 first - http://docs.moodle.org/22/en/Upgrading_to_Moodle_2.2.
5. After you have installed Moodle 2.2, now upgrade to Moodle 2.4 with this new topcoll -
http://docs.moodle.org/24/en/Upgrading_to_Moodle_2.4 - but before initiating the upgrade you can copy the
new (i.e. this) 'topcoll' folder to '/course/format'.
6. Now follow 'Upgrading from Moodle 2.2' below please.
INFO: Having no 'topcoll' folder in '/course/format' is fine as the courses that use it are not accessed and
both the old and new versions will confuse an intermediate 2.2 version and cause it's installation to fail.

Upgrading from Moodle 2.2
-------------------------
1. Put Moodle in 'Maintenance Mode' so that there are no users using it bar you as the administrator - if you have
not already done so.
2. In '/course/format/' move old 'topcoll' directory to a backup folder outside of Moodle - if you have not
already done so.
3. Copy this new 'topcoll' folder to '/course/format/'.
4. Upgrade to Moodle 2.4 by being logged in as 'admin' and clicking on 'Home'. If you have previously upgraded but
'topcoll' was an old version and the upgrade failed, this should still work.
5. Follow installation instructions above.
6. Put Moodle out of Maintenance Mode.
NOTE: If the automated upgrade fails for which can be seen by getting errors when using a Collapsed Topics course,
then please follow this.
Please carry on if a table / field has been removed / changed / already exists as it should still work - this
is to cope with the different possible scenarios. These instructions are written with the MySQL database in
mind, however should work with other database engines but the types should be compared with other tables in
the database to get an idea of what they should be. If possible please kindly feedback to me any additional
information you discover so I can update these instructions - contact details at the very bottom.
The table prefix i.e, 'mdl_' is not stated in the instructions but ensure you know what yours is and use
it with the table names.
1. In your database:
2.1 Rename the table 'format_topcoll_layout' to 'format_topcoll_settings'.
2.2 With the table 'format_topcoll_settings' change all integer types to signed if using a MySQL database.
2.3 If the table 'format_topcoll_settings' does not exist, then create it and add the following fields
in this order:
2.3.1 'id' of type 'BIGINT(10)' type, not null, auto increment, no zero fill with a null default value - the same
as any other 'id' field in the other tables. Make it the primary key.
2.3.2 'courseid' of type 'BIGINT(10)' type, not null, no auto increment, no zero fill with a null default value - the
same as the 'course' field in the 'course_sections' table bar the default value.
2.3.3 'layoutelement' of type 'TINYINT(2)' type, not null, no auto increment, no zero fill with a default value
of '1'.
2.3.4 'layoutstructure' of type 'TINYINT(1)' type, not null, no auto increment, no zero fill with a default value
of '1'.
2.4 With the table 'format_topcoll_settings' append three new fields of 'VARCHAR(6)' type, not null, called
'tgfgcolour', 'tgbgcolour' and 'tgbghvrcolour' in that order with the default values of '000000', 'e2e2f2'
and 'eeeeff' respectively.
2.5 With the table 'format_topcoll_settings' append a new field 'layoutcolumns' after the 'layoutstructure' field
and with identical size, type and attributes. The default is '1'. i.e:
2.5.1 'layoutcolumns' of type 'TINYINT(1)' type, not null, no auto increment, no zero fill with a default value
of '1'.
2.6 Drop the table 'format_topcoll_cookie_cnsnt'.

Uninstallation
==============
1. Put Moodle in 'Maintenance Mode' so that there are no users using it bar you as the administrator.
2. It is recommended but not essential to change all of the courses that use the format to another. If this is
not done Moodle will pick the last format in your list of formats to use but display in 'Edit settings' of the
course the first format in the list. You can then set the desired format.
3. In '/course/format/' remove the folder 'topcoll'.
4. In the database, remove the table 'format_topcoll_settings' along with the entry for 'format_topcoll'
('plugin' attribute) in the table 'config_plugins'. If using the default prefix this will be
'mdl_format_topcoll_settings' and 'mdl_config_plugins' respectively.
5. Put Moodle out of Maintenance Mode.

Course Backup and Restore Instructions
======================================
1. Backup as you would any other course. The layout configuration will be stored with the course settings.
2. Restore as you would any other course. If you are offered the option of 'Overwrite Course Configuration'
you must say 'Yes' to have thelayout configuration restored otherwise the restored course will retain the
layout it previously had or the default in the 'config.php' file as mentioned in the 'Installation'
instructions above depending on the situation.
3. Note: I believe that if you restore a Collapsed Topic's course on an installation that does not have the
format then it will work and become the default course format. However the layout data will not be
stored if you install Collapsed Topic's at a later date.

Remembered Toggle State Information
===================================
The state of the toggles are remembered beyond the session on a per user per course basis though the employment
of a user preference. This functionality is now built in from previous versions. You do not need to do anything.

Icon Sets
=========
Icon sets allow you to choose what is the most appropriate set of icons to use for a given courses demographic. They
are set on a per course basis but with all the functionality of the other settings in respect to a default and resetting
the current or all courses.

If you want to change what icon represents which state / action, then edit 'styles.css' and change the selectors with
the 'background' attribute with a 'toggle-...' type class within them. There are selectors for both the 'toggles' and
the 'toggle all' functionality. For example:

body.jsenabled .course-content ul.ctopics li.section .content .toggle-arrow a.toggle_closed {
background-image: url([[pix:format_topcoll|arrow_right]]);
}

#toggle-all .content .toggle-arrow h4 a.off {
background-image: url([[pix:format_topcoll|arrow_down]]);
}

If you would like your own icon set, either replace the icons in the 'pix' folder, deduce how the code works or better
still create new icons yourself and ask me to add them to the release. If you do the latter then the icons must be your
own for which you grant the same GPL licence as [Moodle](http://www.gnu.org/copyleft/gpl.html) or provide direct evidence
of the originator under the same licence. The icons must be 24x24 pixels with a transparent background.

Known Issues
============
1. If you get toggle text issues in languages other than English please ensure you have the latest version of Moodle installed.
More information on http://moodle.org/mod/forum/discuss.php?d=184150.
2. The MyMobile theme is not quite as implemented as the previous versions but does work, please see http://tracker.moodle.org/browse/MDL-33115.
If your version does not have MDL-38422 implemented, then please follow these instructions:

At the bottom of 'general.php':

<?php echo $OUTPUT->standard_end_of_body_html() ?>
Moodle 2.4

Version information

Version build number
2013041100
Version release name
2.4.4
Can be updated from
2.4.3.1.1 (2013031600)
Can be updated to
2.5.0.1 (2013041500), 2.4.4.1, 2.4.4.2 (2013041102)
Maturity
Stable version
MD5 Sum
b6c9441bc1e4ca9e4070c32ab3318028
Supported software
Moodle 2.4

Version control information

Version control system (VCS)
GIT
VCS repository URL
VCS branch
MOODLE_24
VCS tag
V2.4.4

Default installation instructions for plugins of the type Course formats

  1. Make sure you have all the required versions.
  2. Download and unpack the module.
  3. Place the folder (eg "myformat") in the "course/format" subdirectory.
  4. Visit http://yoursite.com/admin to finish the installation