MoodleDocs - User contributions [en]

Development:XMLDB defining an XML structure

2007-04-16T17:11:43Z

GregLyon: /* The XMLDB editor */

[[Development:XMLDB Documentation|XMLDB Documentation]] > [[Development:XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the exact RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the edition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Miscellaneous tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Coding#Database_structures| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB Problems#NOT NULL fields using a DEFAULT <nowiki>''</nowiki> clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## This convention is only applicable for relations INSIDE one file. Don't generate FK constraints against other files (courseid, userid), use indexes there.
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://moodle.cvs.sourceforge.net/moodle/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false), '''enum''' (true/false), '''enumvalues''' (the list of values if the field has been declared as enum, for example <tt>'frog','toad','newt'</tt>) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' that conform it. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://moodle.cvs.sourceforge.net/*checkout*/moodle/moodle/lib/db/install.xml Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://moodle.cvs.sourceforge.net/moodle/moodle/lib/xmldb/xmldb.dtd?view=markup automatically generated DTD] for the XMLDB files. Also one [http://moodle.cvs.sourceforge.net/moodle/moodle/lib/xmldb/xmldb.xsd?view=markup automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:Developer]]
[[Category:XMLDB]]

Development:Question type plugin how to

2007-03-29T20:29:17Z

GregLyon: /* Getting started */

{{Quiz developer docs}}
To follow this guide, you need to get hold of the qtype_NEW plugin template. You can get it from CVS in the contrib area or from the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database]. The rest of this guide is just a copy of the README.txt file from in there. (Or is the readme file a copy of this page?)

==New question type template README file==

Welcome to the new question type template.

This blank skeleton is a good place to start if you want to implement your own Moodle question type plugin.

Another good way to start is by looking at an existing question type that has good documentation in the code like TODO (if there is one, otherwise we'll hope that Tims will "light the way" :-) )

The latest version of the template can be found in CVS in http://moodle.cvs.sourceforge.net/moodle/contrib/plugins/question/type/TEMPLATE/ (was in contrib/qtype_NEW module). Because you want your own copy do a cvs export, not a cvs checkout. The package can also been downloaded from [http://moodle.org/mod/data/view.php?d=13&rid=443 the Modules and plugins database].

The latest version of this help can be read (nicely formatted) at https://docs.moodle.org/en/How_to_write_a_question_type_plugin

'''WARNING, THIS TEMPLATE IS NOT COMPLETE YET!'''

==Getting started==

Before you get to the interesting bit, you need to do a bit of file-renaming and search-and-replacing to turn this generic template into your own question type. You need to have chosen two things

;The identifier for your question type
:This is a string of lowercase letters and perhaps underscores that the Moodle code uses to refer to your question type. This needs to be unique, so perhaps start it with your initials. For example, all the quetions types I create while working at the OU will be referred to as ou_something. For the rest of these instructions, I will assume you have chosen 'myqtypeidentifier'.
;The name of your question type
:This is the name that people will see in the Moodle User-interface (in the English translation). For these instructions I will assume you have chosen 'My Question Type Name'.

<strong>NOTE:</strong> depending on where you got the template, some of the files and folders may be called TEMPLATE instead of QTYPEID. The contents of the files will still contain the text QTYPEID in either case.

Then you need to

# Rename the directory question/type/QTYPEID to question/type/myqtypeidentifier.
# Rename the language file lang/en_utf8/qtype_QTYPEID.html to lang/en_utf8/qtype_myqtypeidentifier.html
# Rename the help file lang/en_utf8/help/quiz/QTYPEID.html to lang/en_utf8/help/quiz/myqtypeidentifier.html
# Search and replace 'QTYPEID' with 'myqtypeidentifier' in all the files. You should find:
#* 2 occurrences in the language file
#* 1 occurrence in db/install.xml
#* 5 occurrences in simpletest/testquestiontype.php
#* 3 occurrences in editquestion.html
#* 1 occurrence in editquestion.php
#* 3 occurrences in questiontype.php
# Search and replace 'QTYPENAME' with 'My Question Type Name' in all the files. You should find:
#* 1 occurrence in the help file
#* 3 occurrences in the language file
#* 2 occurrences in questiontype.php
# Search and replace YOURNAME with your name. (This is only in the comments at the top of each file so it is not critical, but surely you want to take credit for your work.) You should find one occurrence in:
#* the language file.
#* simpletest/testquestiontype.php
#* editquestion.html
#* editquestion.php
#* questiontype.php
# Search and replace YOUREMAILADDRESS with your email address. (Again, this is only in the file header comments, but it is helpful if people can contact you if they have any questions about your code.) You should find:
#* There should be one occurrence of YOUREMAILADDRESS in each of the files listed under YOURNAME.
# Search and replace YOURPACKAGENAME with a package name for your code. This is used by PHPdoc when building the documentation for your classes. I suggest you make up one package name for all the question types you write. For example all the question types I write are in the package ou_questiontypes.
#* There should be one occurrence of YOURPACKAGENAME in each of the files listed under YOURNAME.
# Edit icon.gif to make an icon that represents your question type.

Finally, so you can test your code while working on it, you need to copy the lang and question folders on top of the folders in your Moodle test installation. This copy should not ovewrite any existing files. It should just add some new files and folders to that directory tree.

==Now for the interesting bit==

Now you need to write the code to

# Create any database tables you need. This works just like normal in Moodle with the files in the db directory and the version.php file. If you don't need to create any database tables, you can delete the db directory.
# Create the editing form for you question type, and the code to populate it. That means adding code to the files editquestion.html and editquestion.php.
# Create the template that will display the question to the student. This is in display.html. To make good flexible formating you should use CSS classes and use already existing ones when possible. An easy way to find which existing CSS classes exist is TODO
# Implement the rest of the question type class. This is in questiontype.php. You need to
## TODO finish writing this section.
# Make sure that the language file contains all the strings you refer to. Note that some of the strings you want may already be in the qtype_base.php and moodle.php language files in Moodle core. If so, use the existing strings. An easy way to find the existing strings is TODO
# Write the help file for your question type, and any other help files you need.
# Write a set of unit tests for you question type.

All the places in the code where you need to do things are marked TODO, and there are comments right there giving more detailed instructions.

''Note that these comments are not complete or accurate yet. I have only just started implementing my own question type, and I will be filling in those comments and finishing this document as I go along.''--[[User:Tim Hunt|Tim Hunt]] 16:29, 25 August 2006 (CDT)

==When you have finished==

Consider checking your question type into the contrib area of the Moodle CVS server (if you have access) so that other people can share it.

Add your new question type to the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database].

[[Category:Developer]]
[[Category:Quiz]]

Development:Question type plugin how to

2007-03-29T20:19:51Z

GregLyon: /* New question type template README file */

{{Quiz developer docs}}
To follow this guide, you need to get hold of the qtype_NEW plugin template. You can get it from CVS in the contrib area or from the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database]. The rest of this guide is just a copy of the README.txt file from in there. (Or is the readme file a copy of this page?)

==New question type template README file==

Welcome to the new question type template.

This blank skeleton is a good place to start if you want to implement your own Moodle question type plugin.

Another good way to start is by looking at an existing question type that has good documentation in the code like TODO (if there is one, otherwise we'll hope that Tims will "light the way" :-) )

The latest version of the template can be found in CVS in http://moodle.cvs.sourceforge.net/moodle/contrib/plugins/question/type/TEMPLATE/ (was in contrib/qtype_NEW module). Because you want your own copy do a cvs export, not a cvs checkout. The package can also been downloaded from [http://moodle.org/mod/data/view.php?d=13&rid=443 the Modules and plugins database].

The latest version of this help can be read (nicely formatted) at https://docs.moodle.org/en/How_to_write_a_question_type_plugin

'''WARNING, THIS TEMPLATE IS NOT COMPLETE YET!'''

==Getting started==

Before you get to the interesting bit, you need to do a bit of file-renaming and search-and-replacing to turn this generic template into your own question type. You need to have chosen two things

;The identifier for your question type
:This is a string of lowercase letters and perhaps underscores that the Moodle code uses to refer to your question type. This needs to be unique, so perhaps start it with your initials. For example, all the quetions types I create while working at the OU will be referred to as ou_something. For the rest of these instructions, I will assume you have chosen 'myqtypeidentifier'.
;The name of your question type
:This is the name that people will see in the Moodle User-interface (in the English translation). For these instructions I will assume you have chosen 'My Question Type Name'.

Then you need to

# Rename the directory question/type/QTYPEID to question/type/myqtypeidentifier.
# Rename the language file lang/en_utf8/qtype_QTYPEID.html to lang/en_utf8/qtype_myqtypeidentifier.html
# Rename the help file lang/en_utf8/help/quiz/QTYPEID.html to lang/en_utf8/help/quiz/myqtypeidentifier.html
# Search and replace 'QTYPEID' with 'myqtypeidentifier' in all the files. You should find:
#* 2 occurrences in the language file
#* 1 occurrence in db/install.xml
#* 5 occurrences in simpletest/testquestiontype.php
#* 3 occurrences in editquestion.html
#* 1 occurrence in editquestion.php
#* 3 occurrences in questiontype.php
# Search and replace 'QTYPENAME' with 'My Question Type Name' in all the files. You should find:
#* 1 occurrence in the help file
#* 3 occurrences in the language file
#* 2 occurrences in questiontype.php
# Search and replace YOURNAME with your name. (This is only in the comments at the top of each file so it is not critical, but surely you want to take credit for your work.) You should find one occurrence in:
#* the language file.
#* simpletest/testquestiontype.php
#* editquestion.html
#* editquestion.php
#* questiontype.php
# Search and replace YOUREMAILADDRESS with your email address. (Again, this is only in the file header comments, but it is helpful if people can contact you if they have any questions about your code.) You should find:
#* There should be one occurrence of YOUREMAILADDRESS in each of the files listed under YOURNAME.
# Search and replace YOURPACKAGENAME with a package name for your code. This is used by PHPdoc when building the documentation for your classes. I suggest you make up one package name for all the question types you write. For example all the question types I write are in the package ou_questiontypes.
#* There should be one occurrence of YOURPACKAGENAME in each of the files listed under YOURNAME.
# Edit icon.gif to make an icon that represents your question type.

Finally, so you can test your code while working on it, you need to copy the lang and question folders on top of the folders in your Moodle test installation. This copy should not ovewrite any existing files. It should just add some new files and folders to that directory tree.

==Now for the interesting bit==

Now you need to write the code to

# Create any database tables you need. This works just like normal in Moodle with the files in the db directory and the version.php file. If you don't need to create any database tables, you can delete the db directory.
# Create the editing form for you question type, and the code to populate it. That means adding code to the files editquestion.html and editquestion.php.
# Create the template that will display the question to the student. This is in display.html. To make good flexible formating you should use CSS classes and use already existing ones when possible. An easy way to find which existing CSS classes exist is TODO
# Implement the rest of the question type class. This is in questiontype.php. You need to
## TODO finish writing this section.
# Make sure that the language file contains all the strings you refer to. Note that some of the strings you want may already be in the qtype_base.php and moodle.php language files in Moodle core. If so, use the existing strings. An easy way to find the existing strings is TODO
# Write the help file for your question type, and any other help files you need.
# Write a set of unit tests for you question type.

All the places in the code where you need to do things are marked TODO, and there are comments right there giving more detailed instructions.

''Note that these comments are not complete or accurate yet. I have only just started implementing my own question type, and I will be filling in those comments and finishing this document as I go along.''--[[User:Tim Hunt|Tim Hunt]] 16:29, 25 August 2006 (CDT)

==When you have finished==

Consider checking your question type into the contrib area of the Moodle CVS server (if you have access) so that other people can share it.

Add your new question type to the [http://moodle.org/mod/data/view.php?id=6009 modules and plugins database].

[[Category:Developer]]
[[Category:Quiz]]

Development:lib/formslib.php Usage

2007-03-09T19:59:02Z

GregLyon: /* Basic Usage in A Normal Page */

{{Formslib}}
==Usage of Formslib==

There are many phpdoc style comments in lib/formslib.php

course/edit.php and the included course/edit_form.php provide a good example of usage of this library.

Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.

We created some special wrapper functions for moodle. $mform->get_data() returns null if no data has been submitted or validation fails or returns an object with the contents of the submitted data.

===Basic Usage in A Normal Page===

Generally the structure of a page with a form on it looks like this :

<pre>
require_once('pathtoformdesctiption');
//you'll process some page parameters at the top here and get the info about
//what instance of your module and what course you're in etc. Make sure you
//include hidden variable in your forms which have their defaults set in set_data
//which pass these variables from page to page

$mform = new yourmod_formfunction_form();//name of the form you defined in file above.
//default 'action' for form is strip_querystring(qualified_me())
if ($mform->is_cancelled()){
//you need this section if you have a cancel button on your form
//here you tell php what to do if your user presses cancel
//probably a redirect is called for!
} else if ($fromform=$mform->get_data()){
//this branch is where you process validated data.

} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.
//setup strings for heading
print_header_simple($streditinga, '',
"<a href=\"$CFG->wwwroot/mod/$module->name/index.php?id=$course->id\">$strmodulenameplural</a> ->
$strnav $streditinga", $mform->focus(), "", false);
//notice use of $mform->focus() above which puts the cursor
//in the first form field or the first field with an error.

//call to print_heading_with_help or print_heading? then :

//put data you want to fill out in the form into array $toform here then :

$mform->set_data($toform);
$mform->display();
print_footer($course);

}</pre>

===Defining Your Form Class===

The form class tells us about the structure of the form. It is encouraged for you to put this in file called {function}_form.php probably in the same folder in which the page that uses it is located. The name of your class should be {modname}_{funciton}_form eg. forum_post_form or course_edit_form. These classes will extend class moodleform.

Note the name you give the class is used as the id attrbute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to selectable in CSS by theme designers who may want to tweak the css just for that form.

====definition()====

[[Development:lib/formslib.php_Form_Definition|Help is here for defining your form]] by defining a function definition() in your form class that sets up your form structure.

===Use in Activity Modules Add / Update Forms===

Syntax is the same in activity modules to create your update / add page. We are still supporting mod.html but if you want to use the new formslib then you can in Moodle 1.8 just include in your module directory the file mod_form.php instead of mod.html and it will be automatically detected. Inside this file you define a class with class name '{modname}__mod_form' which extends the class 'moodleform_mod'. See many examples of the core modules which have been converted to use formslib already.

====defaults_preprocessing====

For activity modules you use the same syntax to define your form. You may also want to override method defaults_preprocessing this can be used to take the data from the data base and tell the form how to fill out defaults in the form with this data. For example in the forum module in forum/mod_form.php we needed to tick an enable check box if a date had been selected in the date select. Normally data is loaded from the database and directly loaded into form fields with the same name as the database record you only need to use defaults_preprocessing if there isn't this one to one relationship. Another example is the lesson/mod_form.php which takes the data from the database and unserializes it. choice/mod_form.php shows an exampe of loading data from another db table referred to by a foreign key, to include in the form.

====Post Processing Still Done in lib.php Functions====

Post processing of data is done in lib.php functions modname_add_instance and modname_update_instance after the data has been validated. When migrating a from little change needs to be made in the post processing often. An exception is that date and date_time_selector fields automatically have their submitted data turned into timestamps so you don't need to do this in your add and update functions anymore.

====Automatically Including Standard Activity Module Form Elements====

Standard activity module form elements are automatically included using the moodleform_mod method standard_coursemodule_elements(). The default is to include a visibility and groupsmode select box and to include all necessary hidden fields. You can pass a parameter false to tell the method that your module doesn't support groups and so you don't want the groupsmode select button.

[[Category:Formslib]]

Development:CVS for developers

2006-10-09T16:48:23Z

GregLyon: /* Feature branches for large changes */

'''CVS''' is the Concurrent Versioning System, a commonly-used way of managing source code for large software projects. CVS keeps all versions of all files so that nothing is ever lost, and usage by different people is tracked. It also provides ways to merge code if two or more people are working on the same file. All code and all versions are stored on a central server (in the case of Moodle, at Sourceforge). The [http://cvsbook.red-bean.com/cvsbook.html CVS book] holds more information about CVS than you need.

If you just want to download Moodle using CVS to run a site, then you probably don't need this page - please see [[CVS for Administrators]] instead.

==Joining the project as a developer==

So, you've been offered CVS write access to help us develop and maintain Moodle! [http://sourceforge.net/project/memberlist.php?group_id=30935 Welcome aboard]!

To be able to write changes into [http://moodle.cvs.sourceforge.net/moodle/moodle/ Moodle's CVS archive], you first need to have an account at Sourceforge ([http://sourceforge.net/account/newuser_emailverify.php registration is free and easy]). For the examples on this page, let's assume your username is myusername and your password is mypassword.

Once you have a working Sourceforge account, contact [http://moodle.com/helpdesk Martin Dougiamas] so he can set up your account with write access to particular Moodle directories.

To avoid being prompted for mypassword every time you run a CVS command, follow [http://sourceforge.net/docman/display_doc.php?docid=761&group_id=1 the Sourceforge directions for using authorized keys]. This step is optional, but it can make your CVS experience a lot nicer.

With that done, you should have all the permissions you need, so you just need to set up your machine and download the current sources so you can start working on them. There is no need to read the [https://sourceforge.net/docs/E04 Sourceforge CVS documentation] unless you are interested.

==CVS modules==

Within CVS, the word "modules" refers to separate collections of code. In Moodle we have the following modules within our repository:

* '''moodle''' - the main Moodle source code
* '''contrib''' - user contributions and other assorted code in development
* '''mysql''' - a customised phpMyAdmin to plug into Moodle for database admin
* '''windows-cron''' - a small package that makes cron possible on Windows systems
* '''docs''' - various extra user-contributed documentation

Most people are working on the existing features in the moodle module, but many are also contributing new ideas in the contrib modules. Once code reaches a certain level of maturity in the contrib area, it can be migrated over into the main moodle tree.

==Basic CVS commands==

===CVS on Unix===

Sourceforge CVS uses ssh as a transport layer for security, so you will have to set a CVS_RSH environment variable in your Unix shell. It's best to put these commands in your .bashrc or .cshrc so you don't have to type it all the time:
setenv CVS_RSH ssh (for csh, tcsh etc)
export CVS_RSH=ssh (for sh, bash etc)

Next, you can check out the latest development version of Moodle using this (all one line). NOTE: Don't try to do run this first CVS command over an existing moodle installation: start fresh with a new directory!:
cvs -z3 -d:ext:myusername@moodle.cvs.sourceforge.net:/cvsroot/moodle co moodle

The command is similar for other CVS modules:
cvs -z3 -d:ext:myusername@moodle.cvs.sourceforge.net:/cvsroot/moodle co contrib

Note that you will be prompted for mypassword for each command unless you set up authorized keys.

Now, you should have a new 'moodle' directory. You can rename it and move it around if you like. Go into it:
cd moodle

All the latest Moodle files should be in there. You can now change files in your copy. To compare your files and directories against the main CVS copy on the server use cvs diff, e.g.:
cvs diff -c config-dist.php
cvs diff -c lang

To fetch the latest updates from the server use:
cvs update -dP

To copy your new files back to the server you would do something like:
cd lang/ca
cvs commit

You will be prompted to add some comments (depends on your default text editor) ... add a meaningful comment and close the editor ... the files will be sent to Sourceforge and stored. Done!

To save more time you can put default arguments into a file called .cvsrc in your home directory. For example, mine contains:
diff -c
update -dP

Try 'cvs help' for more details ...

===CVS on Mac OSX===

You can follow the same instructions as for Unix (above) in a terminal window. However, the cvs command is not installed by default in an OSX. You first need to install the XCode Tools. You should find this on your original installation disk. Failing that it can be downloaded (a fairly hefty download) from the Apple developer web site ([http://developer.apple.com]).

===CVS on Windows===

First, you need to download a completely fresh copy of Moodle using your developer account.

1. Get TortoiseCVS from tortoisecvs.org and install it, then reboot.

2. Find or create a new folder somewhere where you want Moodle to be downloaded to.

3. Right-mouse-click that folder and choose "CVS Checkout" from the menu. You should see a dialog box.

4. Copy this text into the CVSROOT field (using your own username!):

:ext:myusername@moodle.cvs.sourceforge.net:/cvsroot/moodle

5. Under the "Module" field, type "moodle" to get the latest development version of Moodle, "contrib" to get the contributions directory, or "mysql" to get the MySQL Admin module.

6. Press the button: "OK" and everything should be downloaded.

A dialog box should show all the files being downloaded, and after a while you should have a complete copy of Moodle. After this first checkout, you can fetch the latest updated files from the CVS server:

# Right-mouse-click on your Moodle folder (or any file) and select "CVS Update".
# Sit back and watch the logs scroll by. Take note of conflicts that may occur if your local code has changes that conflict with the incoming versions - you will need to edit these files and resolve the conflicts manually.

After modifying files (you will notice their icons change from green to red!), you can commit them back to the CVS server like this:

# Right-mouse-click on your Moodle folder (or any file) and select "CVS Commit...".
# In the dialog box, type a clear description of the changes you are committing.
# Click "OK". Your changes will be sent to the server.

==Working with branches==

This diagram shows how the main moodle module branches into different versions over time.

[[Image:Cvstree.png|CVS tree]]

To see all the current tags and branches that are available, use this command on any old file (such as index.php in the top moodle directory):
cvs status -v index.php

Some tagging guidelines:
* Tag and branch names should always be all upper-case.
* Tags and branches should ALWAYS be applied to the entire module (all of Moodle). Don't tag individual files or directories.
* We don't allow renaming of tags because people may be relying on them, so get them right the first time!

===Trunk development===

The Trunk of CVS is the main development version of Moodle. In CVS it is also known as the HEAD, or default branch.

Moodle developers try to keep this stable as possible, but as it usually contains new code it probably has bugs and small instabilities.

Every now and then we decide the product has enough features to make a release. At this time, the trunk is tagged with a MOODLE_XX_BETA tag (in case we ever want to roll back to that point) and a new branch is formed for the release, called MOODLE_XX_STABLE.

A Beta package is also released at this point - it's for testers who don't use CVS but want to test the latest features and report bugs.

===Stable branches for each release===

As soon as the stable branch MOODLE_XX_STABLE is created, development efforts will fork into two streams for a while. Some people may continue working on new features in the trunk for the next release, but most developers should be concentrating on using the current STABLE branch and fixing bugs that are found in it.

You can switch your local copy of Moodle to the STABLE version using the following command in Unix from the root directory:
cvs update -dP -r MOODLE_XX_STABLE

After that, all the commands described above will apply to that stable version. To return to the trunk version just issue:
cvs update -dPA

On Windows clients you should have a menu from which you can choose the branch.

Once the new STABLE branch really stabilises, a release can be declared. Packages are created for distribution and the branch will be tagged (by Martin) with a tag named: MOODLE_XXX

Periodically, bug fixes in the STABLE branch should be merged into the trunk so that they become available in future versions of Moodle. A floating tag called MOODLE_XX_MERGED will be maintained to keep track of the last merge. The procedure for such a merge is as follows:

1. Get out the very latest trunk version.

cvs update -dPA

2. Merge everything on the branch since the last merge, into your trunk version

cvs update -kk -j MOODLE_XX_MERGED -j MOODLE_XX_STABLE

3. Carefully watch the update logs for conflicts, and fix every file that you see with a conflict

4. Check the merged copy back into CVS trunk version

cvs commit

5. Go back to the branch version

cvs update -dPr MOODLE_XX_STABLE

6. Update the floating merge tag so that this process can be repeated next time

cvs tag -RF MOODLE_XX_MERGED

Finally, the values for $version in all the Moodle version.php files within the stable branch should not be updated at all if possible (except the last digit if necessary). The reason is that someone updating from a very stable version to the next very stable version could miss database upgrades that happened on the trunk.

===Feature branches for large changes===

Occasionally, there may be a very large feature that needs to be checked in so several people can work on it, but it is too unstable to be included in the main development trunk.

In these cases a short-term branch can be created to work on the feature, and then merged back into the main trunk as soon as possible. An example called MOODLE_17_WIDGET branch can be seen in the above diagram.

If you need to do this for your new WIDGET feature, follow these steps:

1. Discuss with other developers to make sure it's necessary!

2. Make a new tag on the trunk (for all of moodle) called MOODLE_XX_WIDGET_PRE

cvs tag -R MOODLE_XX_WIDGET_PRE

3. Create your branch called MOODLE_XX_WIDGET

cvs tag -Rb MOODLE_XX_WIDGET

4. Work in that branch until the feature is reasonably stable. Commit as necessary.

cvs commit

5. When ready, merge the whole branch into the trunk, fix conflicts, commit it to the trunk and then abandon the branch.

cvs update -dPA
cvs update -kk -j MOODLE_XX_WIDGET
cvs commit

Good luck, be careful and have fun!

==Tips and Hints==
* [[Tracking Moodle CVS with git]]
* [http://moodle.org/mod/forum/discuss.php?d=34472 Merging Custom Moodle Code With Stable Releases]
* [[Unmerged files]]: To see if you've forgotten to merge any file.

When you have difficulties accessing CVS this may be due to a problem at Sourceforge. You can check the
* [https://sourceforge.net/docs/A04/ Sourceforge status page]
for any news about outages.

[[Category:Developer]]
[[Category:Developer tools]]

[[es:CVS para desarrolladores]]

User:Greg Lyon

2006-06-29T19:01:12Z

GregLyon:

Hello! Currently (June '06) evaluating Moodle 1.6.

Administration FAQ

2006-06-29T18:59:04Z

GregLyon: /* When will Moodle 1.6 be released? */

{{FAQ}}

==Changing text in Moodle==

Text in Moodle may be changed by editing the language files via Administration >> Configuration >> [[admin/lang | Language]].

Please note that language files are overwritten with new versions when upgrading. To avoid this, you may create your own language pack by copying the contents of your language folder into a new folder, making it the default for the site, then editing this instead.

==How do I make my Moodle site homepage look like the moodle.org homepage?==

Please see the theme how-to [[Homepage design|homepage design of moodle.org]] for full details.

== How do the limits on uploaded files work? ==

File upload sizes are restricted in a number of ways - each one in the list restricts the following ones.

1. Firstly, there is a setting in Apache 2 which you may need to change. On Redhat this setting is very low by default, you can change the limit by adding or editing a line in Apache's ''/etc/httpd/conf/httpd.conf'' and/or ''/etc/httpd/conf.d/php.conf'' with the upload size in bytes (different operating systems may have these files in different locations):

LimitRequestBody 10485760

2. PHP also has two more byte limits, which you can set in ''php.ini'' and sometimes in a ''.htaccess'' file:

php_value upload_max_filesize 50000000
php_value post_max_size 50000000

To convert from Bytes to Megabytes use [http://www.onlineconversion.com/computer.htm this convertor ]

Please note that a server re-start may be required for the above changes to take effect.

3. Moodle has a site-wide limit called maxbytes that may be set in Administration >> Configuration >> [[admin/config|Variables]].

4. A limit may be set by teachers in the [[course/edit|Course settings]].

5. Activity modules such as [[Forums]] and [[Assignments]] have their own limits which may be set when adding or editing the activity.

'''See also'''

* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=39625 Detailed instructions to increase the maximum allowed size for uploaded files] forum discussion

== I have forgotten the admin password ==
Firstly, try using the button "Send my details via email". Otherwise, you will need to access the database using MySQL admin. Passwords for all users, including admin, are stored encrypted in the table ''mdl_user''. Copy the guest password (guest) into the admin password field then login using it.

Additional solutions are detailed in the discussions [http://moodle.org/mod/forum/discuss.php?d=18103 change admin's password] and [http://moodle.org/mod/forum/discuss.php?d=4552&parent=38070 login/password].

== My log table has disappeared - No logs found! ==
The most likely cause is that the mdl_log table has become corrupted. It may be repaired using MySQL Admin as follows:

Click the SQL tab, then in the "Run SQL query/queries on database moodle" field type <code>REPAIR TABLE mdl_log</code> and click the Go button.

'''External links'''

*[http://www.databasejournal.com/features/mysql/article.php/10897_3300511_2 Repairing Database Corruption in MySQL]

==My style sheet changes aren't showing up==

Browsers usually cache style sheets and so a forced refresh (CTRL + F5) is required before any changes show up.

== Site-wide scales ==
To add a site-wide scale, available in all courses, follow the Scales link in any course Administration block. Add a new scale, then use the move down arrow to move the scale from custom scales to standard scales.

== Users are being unenrolled for no apparent reason ==
Unenrolment may be controlled by the following:
*The ''longtimenosee'' variable in Administration >> Configuration >> [[admin/config|Variables]] which specifies the time limit for which, if students haven't logged in, they are unenrolled from courses.
*The ''Enrolment duration'' in the [[course/edit|Course settings]] which unenrols students after the specified time has elapsed.

== When will Moodle 1.6 be released? ==

Moodle 1.6 is now released!

== See also ==

*[http://download.moodle.org/modules/integrations.php Moodle Download: Integrations] - MySQL Admin for download

[[Category:Administrator]]
[[Category:FAQ]]

[[es:FAQ Administración]]