MDL-67264 core_course: Activity chooser new feature
[moodle.git] / course / format / README.txt
1 Course formats
2 ==============
4 To create a new course format, make another folder in here.
6 If you want a basic format, you only need to write the 'standard files' listed
7 below.
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.
12 All names below assume that your format is called 'yourformat'.
15 Standard files
16 --------------
18 * yourformat/format.php
20   Code that actually displays the course view page. See existing formats for
21   examples.
23 * yourformat/config.php
25   Configuration file, mainly controlling default blocks for the format.
26   See existing formats for examples.
28 * yourformat/lang/en/format_yourformat.php
30   Language file containing basic language strings for your format. Here
31   is a minimal language file:
33 <?php
34 $string['formatyourformat']='Your format'; // Name to display for format
35 $string['nameyourformat']='section'; // Name of a section within your format
36 ?>
38   The first string is used in the dropdown menu of course settings. The second
39   is used when editing an activity within a course of your format.
41   Note that existing formats store their language strings in the main
42   moodle.php, which you can also do, but this separate file is recommended
43   for contributed formats.
45   You can also store other strings in this file if you wish. They can be
46   accessed as follows, for example to get the section name:
48   get_string('nameyourformat','format_yourformat');
50   Of course you can have other folders as well as just English if you want
51   to provide multiple languages.
54 Optional files (database access)
55 --------------------------------
57 If these files exist, Moodle will use them to set up database tables when you
58 visit the admin page.
60 * yourformat/db/install.xml
62   Database table definitions. Use your format name at the start of the table
63   names to increase the chance that they are unique.
65 * yourformat/db/upgrade.php
67   Database upgrade instructions. Similar to other upgrade.php files, so look
68   at those for modules etc. if you want to see.
70   The function must look like:
72   function xmldb_format_yourformat_upgrade($oldversion) {
73   ...
75 * yourformat/version.php
77   Required if you use database tables.
79   <?php
80   $plugin->version  = 2006120100; // Plugin version (update when tables change)
81   $plugin->requires = 2006092801; // Required Moodle version
82   ?>
85 Optional files (backup)
86 -----------------------
88 If these files exist, backup and restore run automatically when backing up
89 the course. You can't back up the course format data independently.
91 * yourformat/backuplib.php
93   Similar to backup code for other plugins. Must have a function:
95   function yourformat_backup_format_data($bf,$preferences) {
96   ...
98 * yourformat/restorelib.php
100   Similar to restore code for other plugins. Must have a function:
102   function yourformat_restore_format_data($restore,$data) {
103   ...
105   ($data is the xmlized data underneath FORMATDATA in the backup XML file.
106   Do print_object($data); while testing to see how it looks.)
109 Optional file (capabilities)
110 ----------------------------
112 If this file exists, Moodle refreshes your format's capabilities
113 (checks that they are all included in the database) whenever you increase
114 the version in yourformat/version.php.
116 * yourformat/db/access.php
118   Contains capability entries similar to other access.php files.
120   The array definition must look like:
122   $format_yourformat_capabilities = array(
123   ...
125   Format names must look like:
127   format/yourformat:specialpower
129   Capability definitions in your language file must look like:
131   $string['yourformat:specialpower']='Revolutionise the world';
135 Optional file (styles)
136 ----------------------
138 * yourformat/styles.php
140   If this file exists it will be included in the CSS Moodle generates.