MDL-67264 core_course: Activity chooser new feature
[moodle.git] / course / format / README.txt
CommitLineData
6049fb78 1Course formats
ae628043 2==============
3
4To create a new course format, make another folder in here.
5
aa6c1ced
PS
6If you want a basic format, you only need to write the 'standard files' listed
7below.
ae628043 8
9If you want to store information in the database for your format, or control
10access to features of your format, you need some of the optional files too.
11
aa6c1ced 12All names below assume that your format is called 'yourformat'.
ae628043 13
14
15Standard files
6049fb78 16--------------
17
aa6c1ced 18* yourformat/format.php
ae628043 19
aa6c1ced 20 Code that actually displays the course view page. See existing formats for
ae628043 21 examples.
ae628043 22
aa6c1ced
PS
23* yourformat/config.php
24
25 Configuration file, mainly controlling default blocks for the format.
ae628043 26 See existing formats for examples.
aa6c1ced 27
3a915b06 28* yourformat/lang/en/format_yourformat.php
ae628043 29
30 Language file containing basic language strings for your format. Here
31 is a minimal language file:
aa6c1ced 32
ae628043 33<?php
34$string['formatyourformat']='Your format'; // Name to display for format
35$string['nameyourformat']='section'; // Name of a section within your format
36?>
37
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.
aa6c1ced
PS
40
41 Note that existing formats store their language strings in the main
ae628043 42 moodle.php, which you can also do, but this separate file is recommended
43 for contributed formats.
aa6c1ced 44
ae628043 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:
aa6c1ced 47
ae628043 48 get_string('nameyourformat','format_yourformat');
aa6c1ced 49
ae628043 50 Of course you can have other folders as well as just English if you want
51 to provide multiple languages.
aa6c1ced
PS
52
53
ae628043 54Optional files (database access)
55--------------------------------
56
57If these files exist, Moodle will use them to set up database tables when you
58visit the admin page.
59
60* yourformat/db/install.xml
61
62 Database table definitions. Use your format name at the start of the table
63 names to increase the chance that they are unique.
aa6c1ced 64
ae628043 65* yourformat/db/upgrade.php
66
67 Database upgrade instructions. Similar to other upgrade.php files, so look
aa6c1ced
PS
68 at those for modules etc. if you want to see.
69
ae628043 70 The function must look like:
aa6c1ced
PS
71
72 function xmldb_format_yourformat_upgrade($oldversion) {
ae628043 73 ...
aa6c1ced 74
ae628043 75* yourformat/version.php
76
77 Required if you use database tables.
78
79 <?php
80 $plugin->version = 2006120100; // Plugin version (update when tables change)
81 $plugin->requires = 2006092801; // Required Moodle version
82 ?>
83
aa6c1ced 84
ae628043 85Optional files (backup)
86-----------------------
87
88If these files exist, backup and restore run automatically when backing up
89the course. You can't back up the course format data independently.
90
91* yourformat/backuplib.php
92
93 Similar to backup code for other plugins. Must have a function:
94
95 function yourformat_backup_format_data($bf,$preferences) {
96 ...
aa6c1ced 97
ae628043 98* yourformat/restorelib.php
99
100 Similar to restore code for other plugins. Must have a function:
aa6c1ced 101
ae628043 102 function yourformat_restore_format_data($restore,$data) {
103 ...
aa6c1ced 104
ae628043 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.)
aa6c1ced
PS
107
108
109Optional file (capabilities)
ae628043 110----------------------------
aa6c1ced 111
ae628043 112If this file exists, Moodle refreshes your format's capabilities
113(checks that they are all included in the database) whenever you increase
114the version in yourformat/version.php.
aa6c1ced 115
ae628043 116* yourformat/db/access.php
117
aa6c1ced
PS
118 Contains capability entries similar to other access.php files.
119
ae628043 120 The array definition must look like:
aa6c1ced
PS
121
122 $format_yourformat_capabilities = array(
ae628043 123 ...
aa6c1ced
PS
124
125 Format names must look like:
126
ae628043 127 format/yourformat:specialpower
aa6c1ced 128
ae628043 129 Capability definitions in your language file must look like:
aa6c1ced 130
ae628043 131 $string['yourformat:specialpower']='Revolutionise the world';
132
aa6c1ced
PS
133
134
ae628043 135Optional file (styles)
136----------------------
6049fb78 137
ae628043 138* yourformat/styles.php
6049fb78 139
ae628043 140 If this file exists it will be included in the CSS Moodle generates.
44b64a56 141