course/format/README.txt

   1 Course formats
   2 ==============
   3
   4 To create a new course format, make another folder in here.
   5
   6 If you want a basic format, you only need to write the 'standard files' listed
   7 below.
   8
   9 If you want to store information in the database for your format, or control
  10 access to features of your format, you need some of the optional files too.
  11
  12 If you want to override some standard course output component (located in
  13 coure/classes/output/{course|section|cm}_format/*) you need to create an
  14 extend class inside your course/format/yourformat/classes/output.
  15
  16 All names below assume that your format is called 'yourformat'.
  17
  18
  19 Standard files
  20 --------------
  21
  22 * yourformat/format.php
  23
  24   Code that actually displays the course view page. See existing formats for
  25   examples.
  26
  27 * yourformat/config.php
  28
  29   Configuration file, mainly controlling default blocks for the format.
  30   See existing formats for examples.
  31
  32 * yourformat/lang/en/format_yourformat.php
  33
  34   Language file containing basic language strings for your format. Here
  35   is a minimal language file:
  36
  37 <?php
  38 $string['formatyourformat']='Your format'; // Name to display for format
  39 $string['nameyourformat']='section'; // Name of a section within your format
  40 ?>
  41
  42   The first string is used in the dropdown menu of course settings. The second
  43   is used when editing an activity within a course of your format.
  44
  45   Note that existing formats store their language strings in the main
  46   moodle.php, which you can also do, but this separate file is recommended
  47   for contributed formats.
  48
  49   You can also store other strings in this file if you wish. They can be
  50   accessed as follows, for example to get the section name:
  51
  52   get_string('nameyourformat','format_yourformat');
  53
  54   Of course you can have other folders as well as just English if you want
  55   to provide multiple languages.
  56
  57
  58 Optional files (database access)
  59 --------------------------------
  60
  61 If these files exist, Moodle will use them to set up database tables when you
  62 visit the admin page.
  63
  64 * yourformat/db/install.xml
  65
  66   Database table definitions. Use your format name at the start of the table
  67   names to increase the chance that they are unique.
  68
  69 * yourformat/db/upgrade.php
  70
  71   Database upgrade instructions. Similar to other upgrade.php files, so look
  72   at those for modules etc. if you want to see.
  73
  74   The function must look like:
  75
  76   function xmldb_format_yourformat_upgrade($oldversion) {
  77   ...
  78
  79 * yourformat/version.php
  80
  81   Required if you use database tables.
  82
  83   <?php
  84   $plugin->version  = 2006120100; // Plugin version (update when tables change)
  85   $plugin->requires = 2006092801; // Required Moodle version
  86   ?>
  87
  88
  89 Optional files (backup)
  90 -----------------------
  91
  92 If these files exist, backup and restore run automatically when backing up
  93 the course. You can't back up the course format data independently.
  94
  95 * yourformat/backuplib.php
  96
  97   Similar to backup code for other plugins. Must have a function:
  98
  99   function yourformat_backup_format_data($bf,$preferences) {
 100   ...
 101
 102 * yourformat/restorelib.php
 103
 104   Similar to restore code for other plugins. Must have a function:
 105
 106   function yourformat_restore_format_data($restore,$data) {
 107   ...
 108
 109   ($data is the xmlized data underneath FORMATDATA in the backup XML file.
 110   Do print_object($data); while testing to see how it looks.)
 111
 112
 113 Optional file (capabilities)
 114 ----------------------------
 115
 116 If this file exists, Moodle refreshes your format's capabilities
 117 (checks that they are all included in the database) whenever you increase
 118 the version in yourformat/version.php.
 119
 120 * yourformat/db/access.php
 121
 122   Contains capability entries similar to other access.php files.
 123
 124   The array definition must look like:
 125
 126   $format_yourformat_capabilities = array(
 127   ...
 128
 129   Format names must look like:
 130
 131   format/yourformat:specialpower
 132
 133   Capability definitions in your language file must look like:
 134
 135   $string['yourformat:specialpower']='Revolutionise the world';
 136
 137
 138
 139 Optional file (styles)
 140 ----------------------
 141
 142 * yourformat/styles.php
 143
 144   If this file exists it will be included in the CSS Moodle generates.
 145
 146
 147 Optional files (outputs)
 148 ----------------------
 149
 150 By default, the format renderer will use those output classes:
 151
 152 * core_courseformat\output\local\content: for the general course structure
 153 * core_courseformat\output\local\content\*: to render specific course structure parts
 154
 155 * core_courseformat\output\local\content\section: for the complete section output
 156 * core_courseformat\output\local\content\section\*: to render specific section parts
 157
 158 * core_courseformat\output\local\content\cm: for output an activity inside a section
 159 * core_courseformat\output\local\content\cm\*: for speficis parts of the cm output
 160
 161   Your format can override any of this output classes just by creating class
 162   inside your format_yourformat\output\courseformat\* namespace. We recommend to extend the
 163   original class to ensure all element will work as expected.
 164
 165   For example: if you want to change the section header, you should create
 166   format_yourformat\output\section\header, which will extend the original
 167   core_courseformat\output\courseformat\content\section\header class.
 168
 169   By default, only a few format renderer methods are needed to render a course:
 170   - render_content to render a full course content
 171   - course_section_updated used by the course editor to refresh a specific section
 172   - course_section_updated_cm_item used by the course editor to refresh a specific cm item
 173
 174   Formats can override those two methods to use different templates to render a course.