lang/en_utf8/docs/developer.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Moodle Docs: Developers Manual</title>
   6 <link rel="stylesheet" href="docstyles.css" type="TEXT/CSS" />
   7 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   8 </head>
   9
  10 <body>
  11 <h1>Developers Manual</h1>
  12 <blockquote>
  13   <p>This document describes some of Moodle's design and how you can contribute.</p>
  14   <p>It's a bit thin at the moment - better documentation will come eventually!</p>
  15   <p>Sections in this document:</p>
  16   <ol>
  17     <li><a href="#architecture">Moodle architecture</a></li>
  18     <li><a href="#contribute">How you can contribute</a>
  19       <ul>
  20         <li><a href="#activities">Learning activities</a></li>
  21         <li><a href="#themes">Themes</a></li>
  22         <li><a href="#languages">Languages</a></li>
  23         <li><a href="#database">Database Schemas</a></li>
  24         <li><a href="#courseformats">Course formats</a></li>
  25         <li><a href="#doc">Documentation and articles</a></li>
  26         <li><a href="#bugs">Participating in the bug tracker</a></li>
  27       </ul>
  28     </li>
  29   </ol>
  30 </blockquote>
  31 <p>&nbsp;</p>
  32 <h2><a name="architecture"></a>1. Moodle architecture</h2>
  33 <blockquote>
  34   <p>From a system administrator's perspective, Moodle has been designed according
  35     to the following criteria:</p>
  36   <ol>
  37     <li><strong>Moodle should run on the widest variety of platforms</strong><br />
  38       <br />
  39       The web application platform that runs on most platforms is PHP combined
  40       with MySQL, and this is the environment that Moodle has been developed in
  41       (on Linux, Windows, and Mac OS X). Moodle also uses the ADOdb library for
  42       database abstraction, which means Moodle can use <a href="http://php.weblogs.com/ADOdb_manual#drivers">more
  43       than ten different brands of database</a> (unfortunately, though, it can
  44       not yet <em><strong>set up tables</strong></em> in all these databases -
  45       more on this later). <br />
  46       <br />
  47     </li>
  48     <li><strong>Moodle should be easy to install, learn and modify</strong><br />
  49       <br />
  50       Early prototypes of Moodle (1999) were built using <a target="_top" href="http://www.zope.org/">Zope</a>
  51       - an advanced object-oriented web application server. Unfortunately I found
  52       that although the technology was pretty cool, it had a very steep learning
  53       curve and was not very flexible in terms of system administration. The PHP
  54       scripting language, on the other hand, is very easy to get into (especially
  55       if you've done any programming using any other scripting language). Early
  56       on I made the decision to avoid using a class-oriented design - again, to
  57       keep it simple to understand for novices. Code reuse is instead achieved
  58       by libraries of clearly-named functions and consistent layout of script
  59       files. PHP is also easy to install (binaries are available for every platform)
  60       and is widely available to the point that most web hosting services provide
  61       it as standard.<br />
  62       <br />
  63     </li>
  64     <li><strong>It should be easy to upgrade from one version to the next</strong><br />
  65       <br />
  66       Moodle knows what version it is (as well as the versions of all plug-in
  67       modules) and a mechanism has been built-in so that Moodle can properly upgrade
  68       itself to new versions (for example it can rename database tables or add
  69       new fields). If using CVS in Unix for example, one can just do a &quot;cvs
  70       update -d&quot; and then visit the site home page to complete an upgrade.<br />
  71       <br />
  72     </li>
  73     <li><strong>It should be modular to allow for growth</strong><br />
  74       <br />
  75       Moodle has a number of features that are modular, including themes, activities,
  76       interface languages, database schemas and course formats. This allows anyone
  77       to add features to the main codebase or to even distribute them separately.
  78       More on this below in the next section.<br />
  79       <br />
  80     </li>
  81     <li><strong>It should be able to be used in conjunction with other systems</strong><br />
  82       <br />
  83       One thing Moodle does is keep all files for one course within a single,
  84       normal directory on the server. This would allow a system administrator
  85       to provide seamless forms of file-level access for each teacher, such as
  86       Appletalk, SMB, NFS, FTP, WebDAV and so on. The authentication modules allow
  87       Moodle to use LDAP, IMAP, POP3, NNTP and other databases as sources for
  88       user information. Otherwise, there is work yet to do. Features planned for
  89       Moodle in future versions include: import and export of Moodle data using
  90       XML-based formats (including IMS and SCORM); and increased use of style
  91       sheets for interface formatting (so that it can be integrated visually into
  92       other web sites).</li>
  93   </ol>
  94 </blockquote>
  95 <p>&nbsp;</p>
  96 <h2><a name="contribute" id="contribute"></a>2. How you can contribute</h2>
  97 <blockquote>
  98   <p>As mentioned above, Moodle has a number of features that are modular. Even
  99     if you are not a programmer there are things you can change or help with.</p>
 100   <h3><a name="activities" id="activities"></a>Learning Activities</h3>
 101   <blockquote>
 102     <p>These are by far the most important modules, and reside in the 'mod' directory.
 103       There are a number of default modules: assignment, choice, forum, quiz, survey, wiki, etc. Each module is in a separate subdirectory and consists
 104       of the following mandatory elements (plus extra scripts unique to each module):</p>
 105     <ul>
 106       <li>mod.html: a form to set up or update an instance of this module</li>
 107       <li>version.php: defines some meta-info and provides upgrading code</li>
 108       <li>icon.gif: a 16x16 icon for the module</li>
 109       <li>db/: SQL dumps of all the required db tables and data (for each database
 110         type) </li>
 111       <li>index.php: a page to list all instances in a course</li>
 112       <li>view.php: a page to view a particular instance</li>
 113       <li>lib.php: any/all functions defined by the module should be in here.
 114         If the modulename if called widget, then the required functions include:
 115         <ul>
 116           <li>widget_add_instance() - code to add a new instance of widget</li>
 117           <li>widget_update_instance() - code to update an existing instance</li>
 118           <li>widget_delete_instance() - code to delete an instance</li>
 119           <li>widget_user_outline() - given an instance, return a summary of a
 120             user's contribution</li>
 121           <li>widget_user_complete() - given an instance, print details of a user's
 122             contribution<br />
 123           </li>
 124           <li>To avoid possible conflict, any module functions should be named
 125             starting with widget_ and any constants you define should start with
 126             WIDGET_ </li>
 127         </ul>
 128       </li>
 129       <li>Lastly, each module will have some language files that contain strings
 130         for that module. See below.</li>
 131     </ul>
 132     <p>The easiest way to start a new learning activity module is to use the template
 133       in <strong><a href="http://moodle.org/mod/newmodule_template.zip">mod/newmodule_template.zip</a>.</strong>
 134       Unzip it and follow the README inside. </p>
 135     <p>You might also like to post first in the <a href="http://moodle.org/mod/forum/view.php?id=44" target="_top">Activities
 136       modules forum on Using Moodle</a>.</p>
 137     <p>&nbsp;</p>
 138   </blockquote>
 139   <h3><a name="themes" id="themes"></a>Themes</h3>
 140   <blockquote>
 141     <p>Themes (or skins) define the look of a site. A number of simple themes
 142       are provided in the main distribution, but you may want to create your own
 143       theme with your own colours, logo, styles and graphics. </p>
 144     <p>Each theme is in a subdirectory of the &quot;theme&quot; directory, and
 145       contains at least the following files:</p>
 146     <ul>
 147       <li><strong>config.php</strong>: to configure how the CSS files work together. You can build your theme onto the standard or onto any parent theme, can include or exclude several CSS files.</li>
 148       <li><strong>styles.php</strong>: Builds the bridge to the CSS files. You don't need to edit anything.</li>
 149       <li><strong>header.html</strong>: Included at the top of each page. This
 150         is what you need to edit to add a logo at the top of pages, for example.</li>
 151       <li><strong>footer.html</strong>: Included at the bottom of each page.</li>
 152       <li><strong>styles_color.css</strong>: CSS styles for all colour properties.</li>
 153       <li><strong>styles_fonts.css</strong>: CSS styles for fonts, font-size, line-height etc.</li>
 154       <li><strong>styles_layout.css</strong>: CSS styles for the page layout, positioning etc.</li>
 155       <li><strong>styles_moz.css</strong>: CSS styles for Mozilla special rounded corners.</li>
 156     </ul>
 157     <p>To create your own themes for the current versions of Moodle:</p>
 158     <ol>
 159       <li>Copy one of the existing theme folders to one with a new name. I recommend
 160         starting with one of the standard themes. </li>
 161       <li>Edit config.php to meet your demands. </li>
 162       <li>Edit the CSS files with your styles. </li>
 163       <li>Edit header.html and footer.html to add new logos, or change the layout.
 164       </li>
 165     </ol>
 166     <p>Note also that Moodle upgrades <em>may</em> break themes slightly, so check
 167       the release notes carefully if you are using a custom theme.</p>
 168     <p>Please read the detailed description of Moodle themes in the Themes documentation in <a href="http://docs.moodle.org/wiki/Themes">Moodle Docs</a>.</p>
 169     <p>More discussion about themes in the <a target="_top" href="http://moodle.org/mod/forum/view.php?id=46">Themes
 170       forum on Using Moodle</a>. If you create a nice theme that you think others
 171       might want to use, please post your zip file on the themes forum!<br />
 172     </p>
 173   </blockquote>
 174   <h3><a name="languages" id="languages"></a>Languages</h3>
 175   <blockquote>
 176     <p>Moodle has been designed for internationalisation. Each 'string' or 'page'
 177       of text that is displayed as part of the interface is drawn from a set of
 178       language files. Each language is a subdirectory of the directory 'lang'.
 179       The structure of the lang directory is as follows:</p>
 180     <p><strong>lang/en</strong> - directory containing all files for one language
 181       (eg English)</p>
 182     <ul>
 183       <li>moodle.php - strings for main interface</li>
 184       <li>assignment.php - strings for assignment module</li>
 185       <li>choice.php - strings for choice module</li>
 186       <li>forum.php - strings for forum module</li>
 187       <li>quiz.php - strings for quiz module</li>
 188       <li>resource.php - strings for resource module</li>
 189       <li>survey.php - strings for survey module</li>
 190       <li>.... plus other modules if any.<br />
 191         <br />
 192         A string is called from these files using the <strong><em>get_string()</em></strong> or<em> <strong>print_string()</strong> </em>functions. Each string
 193         supports variable substitution, to support variable ordering in different
 194         languages.<em><br />
 195         <br />
 196         </em>eg $strdueby = get_string(&quot;assignmentdueby&quot;, &quot;assignment&quot;,
 197         userdate($date)); <br />
 198         <br />
 199         If a string doesn't exist in a particular language, then the equivalent
 200         in English will automatically be used instead.</li>
 201     </ul>
 202     <p><strong>lang/en/help</strong> - contains whole help pages (for popup context-sensitive
 203       help)</p>
 204     <blockquote>
 205       <p>Main help pages are situated here, while help pages specific to each
 206         module are located in subdirectories with the module's name.</p>
 207       <p>You can insert a helpbutton in a page with the helpbutton function.</p>
 208       <p>eg helpbutton(&quot;text&quot;, &quot;Click here for help about text&quot;);</p>
 209       <p>and for modules:</p>
 210       <p>helpbutton(&quot;forumtypes&quot;, &quot;Forum types&quot;, &quot;forum&quot;);</p>
 211     </blockquote>
 212     <p>Note that you can edit languages online, using the administration web tools
 213       under &quot;Check this language&quot;. This makes it easy to not to only
 214       create new languages but to refine existing ones. If you are starting a
 215       new language, please contact me, <a target="_top" href="http://dougiamas.com/">Martin
 216       Dougiamas</a>. </p>
 217     <p>You might also like to post in the <a target="_top" href="http://moodle.org/mod/forum/view.php?id=43">Languages
 218       forum on Using Moodle</a>. </p>
 219     <p>If you are maintaining a language an ongoing basis, I can give you <a href="?file=cvs.html">CVS
 220       write access to the Moodle source code</a> so that you can directly maintain
 221       the files.</p>
 222   </blockquote>
 223   <h3><a name="database" id="database"></a>Database Schemas</h3>
 224   <blockquote>
 225     <p>Given a working database with defined tables, the intentionally simple
 226       SQL used in Moodle should work fine with a wide variety of database brands.</p>
 227     <p>A problem exists with <strong>automatically creating</strong> new tables
 228       in a database, which is what Moodle tries to do upon initial installation.
 229       Because every database is very different, there doesn't yet exist any way
 230       to do this in a platform-independent way. To support this automation in
 231       each database, schemas can be created that list the required SQL to create
 232       Moodle tables in a particular database. These are files in <strong>lib/db</strong>
 233       and inside the <strong>db</strong> subdirectory of each module.</p>
 234     <p>Currently, only MySQL and PostgreSQL are fully supported in this way (no-one
 235       wrote the schemas for other brands).</p>
 236     <p>Moodle 1.2 will use a new method of database-independent XML schemas that
 237       will make all this unnecessary.</p>
 238   </blockquote>
 239   <p>&nbsp;</p>
 240   <h3><a name="courseformats" id="courseformats"></a>Course Formats</h3>
 241   <blockquote>
 242     <p>Moodle currently supports three different course formats: weekly, topics
 243       and social. </p>
 244     <p>These are a little more connected to the rest of the code (and hence, less
 245       &quot;pluggable&quot;) but it is still quite easy to add new ones.</p>
 246     <p>If you have any ideas for different formats that you need or would like
 247       to see, get in touch with me and I'll do my absolute best to have them available
 248       in future releases.</p>
 249   </blockquote>
 250   <p>&nbsp;</p>
 251   <h3><a name="doc" id="doc"></a>Documentation and articles</h3>
 252   <blockquote>
 253     <p>If you feel like writing a tutorial, an article, an academic paper or anything
 254       else about Moodle, please do! </p>
 255     <p>Put it on the web and make sure you include links to <a target="_top" href="http://moodle.org/">http://moodle.org/</a></p>
 256   </blockquote>
 257   <p>&nbsp;</p>
 258   <h3><a name="bugs" id="bugs"></a>Participating in the bug tracker</h3>
 259   <blockquote>
 260     <p>Finally, I would like to invite you to register on the &quot;bug tracker&quot;
 261       at <a target="_top" href="http://moodle.org/bugs/">http://moodle.org/bugs</a>
 262       so you can file any bugs that you find and perhaps participate in discussing
 263       and fixing them. </p>
 264     <p>&quot;Bugs&quot; not only includes software bugs with current versions
 265       of Moodle, but also new ideas, feature requests and even constructive criticism
 266       of existing features. The beauty of open source is that anyone can participate
 267       in some way and help to create a better product for all of us to enjoy.
 268       In this project, your input is very welcome!</p>
 269   </blockquote>
 270 </blockquote>
 271 <p>&nbsp;</p>
 272 <blockquote>
 273   <blockquote>
 274     <blockquote>
 275       <p align="center">Thanks for using Moodle!<br />
 276         <br />
 277         <a target="_top" href="http://dougiamas.com/">Martin Dougiamas</a>, Lead
 278         Developer </p>
 279     </blockquote>
 280   </blockquote>
 281 </blockquote>
 282 <p>&nbsp;</p>
 283 <blockquote>
 284   <p>&nbsp;</p>
 285 </blockquote>
 286 <p align="center"><font size="1"><a href="." target="_top">Moodle Documentation</a></font></p>
 287 <p align="center"><font size="1">Version: $Id$</font></p>
 288 </body>
 289 </html>