MoodleDocs - User contributions [en]

XMLDB introduction

2010-07-28T12:40:48Z

Josepuib: Wrong verbal tense

[[XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 year old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we find some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

XMLDB introduction

2010-07-28T12:32:20Z

Josepuib: Spelling mistake

[[XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 year old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

lib/formslib.php Usage

2009-10-23T18:02:58Z

Josepuib: missing word

{{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 :

<code php>
require_once('pathtoformdescription');
//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);

}
</code>

===Defining Your Form Class===

The form class tells us about the structure of the form. You are encouraged to put this in a 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}_{function}_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 attribute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to be selectable in CSS by theme designers who may want to tweak the css just for that form.

====definition()====

[[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 form often little changes need to be made in the post processing. 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]]

POAS Assignment development

2009-10-09T16:47:24Z

Josepuib: spelling mistakes

{{Moodle 2.0}}
This was a proposition of Assignment module development from POAS department of Volgograd State Technical University.
We don't want to fork from core, but was forced to do it by Moodle team. So it will be a separate module, that you can use instead of standard assignment. There may be a convertor some time ago.

New module name will be a poasassignment.
== Assignment 1.9 improvements ==
Just several simple, but useful improvements that can be done in stable version too:
# Usability improvement: on submission.php add a combo box to filter the content of the table: Show all/with submissions/await grading. That speed up grading much. See MDL-14238
# New capability: viewownsubmission. Setting it to Deny makes assignment module useful in exam context - collect student's work without their further access to it. See MDL-15356
# Replace link with the number of submissions (for the teacher) with more informative "The ___ of ___ submissions needs grading". MDL-17613

== Refactoring ==
Some areas of assignment can be reworked for greater flexibility and reducing code duplication. Assignment base is actualy an awful, bloated class where all things are intermixed. And any plugin inherits it fully. Some plugins have similar features too, implemented separately. Overall issue for this is MDL-17329.

Some major improvments:
* 'types' will be no longer considered separate activities, just a option in the mod_form
* 'type' plugins, which defines what can be submitted, will be reduced to just that purpose, all workflow would be controlled from main module (reducing numerous duplicates and inconsistences)
* there will be two basic 'type' plugins (text and files), which can be used in any combination (from no one to both)
** no one is effectively an offline task
** files (reworked upload) can serve for both single and multiple files uploads
* there will be possible to create new activities based on this module, inheriting it's main classes, for major workflow customisations, and they will have full access to 'type' plugins
== New Features ==

=== Teams ===
This feature is on hold and may wait for a second version of module. Right now we are more focused on task distribution

One main assumption in the assignment module is need to be eliminated is "one user=one submission=one grade". The quite common practice is grouped assignments, where students can work in small groups on a task. So we need a teams support there. (Well, quite big work as many functions use this assumption).

'''Team''' is a group of students whose work will results in one submission. Teams features:
* submission is one per team, but a grade can be given on per-team or per-student basis
* teacher can define a minimum and maximum number of students in the team
* self-organization (with possibility of confirmation by teacher) or forced by teacher teams
* maximum date of team membership editing
* teacher can add themselves to teamas a mentor, then he only will be notified of events in this team
* 'roles' (or workroles to avoid confusion with Moodle Roles) of people in team (either teacher or student defined) - this is a way to explain who in group will do what
** teacher-defined roles is a list, from which one or several roles can be selected for students
** if teacher doesn't want do define specific roles, students can enter text, explaining their role in the group

=== Individual tasks ===
Individual tasks is quite common situation in the educational process. The module can handle tasks selection and completion.

Individual tasks features:
* adding/editing/deleting of tasks by the teacher
* standart fields: name, description, grade factor (1 by default), min/max teamnumber (if teams activated)
* custom fields, which can be added in any given assignment, of several types: string, text, number, date, menu, file
* some fields can only be accessible to the student once he is selected a task (and it will be approved by a teacher if necessary)
* student's selection (with optional teacher approval), teacher-forced selection or random selection based on a student's selection of subset of tasks fields (number or menu mainly, i.e. some sort of 'complexity' field for example)
* maximum dates of selection (and approval if necessary)
* column with task name (link to the task) when grading
* random filling of some task fields (number or menu mainly) on selection or approval
** there is some problem of misuse of random generator; they are mainly dealt with fact that student's can change task and select new without teacher

=== User interface - tabs ===
Currently assignment have only two main pages: intro/submit (view.php) and grading (submission.php), so it can go away with the link in upper right corner.

New features will require more pages, so it's better to use tabs for them. Tabs visibility will be based on user's capabilities.

Urgent reminders will be places on top (or bottom?) of every tab with color highlighting;
* for students
** if he is late to select a task/become a member of team
** if he is late to submit work
* for teachers
** if student from his/her group asks to delete him from team (or task change)
** if there are students without task/team after date of last approval

=== Grading semi-plugins ===
Sometimes assignments allow for automatic, or semi-automatic grading. It's nice to have options to have a plugin system for this.

=== ''maybe'' One user can get several tasks ===
That needs further discussion. It's something not very uncommon in real word teaching, but somewhat difficult to cope with "one course module=one grade" thing.

=== Tasks workflow ===
Let's see a task workflow in most complicated case (maximum features will be used). States names are somewhat awkward and is subject to change (can anyone propose better names?)

* initially task is '''free''' (1)
* (1) student or teacher can create a team -> '''creating team''' (2)
* (2) student(s) can add themselves to the team, teacher can add students to the team (in last case student notified that he/she was added)
* (2) students can plead to free them from team/task, teacher can disapprove (if allowed) members or task (students is notified if they are disapproved)
* (2) after the team will have at least minimum number of participants -> '''have enough people''' (3)
* (3) all (2) operations still available
* (3) students can confirm his will to work with team(now that he knows all it's members), teacher can approve a team - approvment automatically cleared if team membership changes (people that have approves is notified)
* (3) after the date of last approval, no more changes in teams available for students, (for teachers it's depends on capabilities), if there is an unapproved team the teacher will be shown (and sent) urgent reminder
* (3) after the students (if allowed) approved a team and task -> '''ready''' (4) (if teacher approvment needed) or '''working''' (5) (students and teacher notified)
* (4) after teacher approval -> '''working''' (5) (students notified)
* (4) in case of teacher disapproval -> '''have enough people''' (3) (students notified)
* (5) any student in the team can submit work with flag 'please check our progress' (if allowed), then teacher is notified and able to give comment but not grade (teacher notified, student's notified of comment)
* (5) any student in team can make a normal submit, but it (optionally) may need an approval from other members for grading -> '''await grading''' (6) (teacher notified)
* (6) the teacher can only grade a team in '''await grading''' status
* (6) teacher grades, but grade isn't final -> '''reworking''' (5) (students notified)
* (6) teacher gives final grade -> '''graded''' (7) (students notified)
* (7) person of higher authority will be able to override grade and add something to comment (but maybe not freely edit it, the name of the first grader and regrader will be saved in comment). (students and teacher notified)

Well it's probably looked worse than is. The actual user will see only part of options, and all forms of approval can be disabled.

=== Files handling ===
There is some confusion about files handling in current version of assignment module. This is need to be corrected. So there should be a several types of files:

# '''assignment''' files - files that is showed and accessible to all, and associated with assignment in general even if individual tasks is used (such as guidelines for it's completion that apply to all regardless of individual task);
# '''task''' files - some file(s) that teacher want to give students before they start to work on particular task;
# '''submission''' files - files that was submitted by a particular student (team);
# '''reply''' (comment) files - files that was uploaded by a teacher when grading submitted work, usually rewised versions of submitted files (thanks to A.T. Wyatt comment there)

== Implementation ==

=== New options ===
Let's see an assignment creation/editing screen. Assignment module will keep all existing options.

New options that will be added:
* use individual tasks
* use teams
* last date of approval - active if tasks or teams used, time to which all considerations about group memebrship and tasks selections must be done
* team options (active only if teams selected)
** min and max count of members of team
** the grade will be individual or one per team
** if students must confirm it will to work with team (first student, who create a team, may not be happy with someone who add yourself to it later)
** if teacher must confirm team membership
** if all team members must confirm a submission before grading
* individual task options (active only if tasks is selected)
** allow using same tasks - can several students do one task or all tasks must be different?
** allow using same tasks in one group
** individual date - allow individual due dates to the task
** individual team members count - if teams used, can particular task override min/max number of students in team
** teacher must confirm task selection
** random task assignment

=== DB structure ===
[[Image:db_shema.jpg]]

The new db structure have such tables:
* '''poasassignment''' - main table which have new options :
*# maxmembersontask - maximum count of members which must to do the task
*# minmembersontask - minimum count of members which must to do the task
*# mintaskonmember - minimum count of tasks for one member(needs discussion)
*# maxtaskonmember - maximum count of tasks for one member(needs discussion)
*# timedistrib - initial time for task distribution
*# timeconfirmation - the date after that a student not may create/come into new working group
*# timereception - start time for tasks reception
*# flags - all binary options
* '''poasassignment_tasks''' - table for task list of instance of activity:
*# name - the name of task
*# descripiton - task "body"
*# deadline - individual date for task reception
*# factor - factor for grade
*# maxmembers - maximum workgroup members on task
*# minmembers - minimum workgroup members on task
* '''poasassignment_fields''' - define list of custom fields:
*# ftype - type of the field
*# name - name of the field
*# showintable - additional column in table of tasks
*# maxvalue - maximum value for the field(only numbers)
*# minvalue - minimum value for the field(only numbers)
*# optional - optional field?
*# rndparam - if this field used to define filter for random selection of task
*# rndshow - if this field will get random value on task selection (number or menu fields only)
* '''poasassignment_field_consts''' - define consts for the fields type of list
* '''poasassignment_values''' - values for particular task/workgroup
* '''poasassignment_workgroups''' - table for teams, also submissions stuff go there
* '''poasassignment_workgroup_members''' - members of teams, grade stuff go there:
*# userid -
*# grade - this is the grade for submission
*# submissioncomment -
*# format,teacher,timemarked,mailed - old fields of assignment_submissions
*# ownrole - role which student want implement during task execution
*# finalgrade - final grade(yes/no)?
*# deletefrom - please kick me from this working group (or task)
*# deletecomment - explanation why student needs to delete from this working group
* '''poasassignment_role''' - roles for the task:
*# one task have many roles
*# one student perform many roles
Rethink tables/columns, define how a type plugin can use db, rename workgroups into teams everywhere --[[User:Oleg Sychev|Oleg Sychev]] 11:12, 11 September 2009 (UTC)
=== Tabs ===

==== Info/submit ====
This is an initial tab, that will work basically the same as before.

New abilities:
* show additional dates (i.e. dates of last approval and so on)
* student: show individual task (?tasks?) when the individual tasks is selected
* student: show task status (see workflow of the task above)
* student: show team members (when teams used)
* student: can approve team and submission, select or type his roles
* teacher: the number of submissions will be shown JFI as there is a tab for grading now (maybe as a link, just as in quiz now - it must be moved to down center area)
* teacher: the number of submissions will be showed as <need grading>/<all submissions>

==== Custom fields ====
This tab is for managing custom fields for the tasks. The author can add/edit/delete fields there.

==== Tasks ====
New tab, accessible when individual task feature activated.

Abilities:
* teacher: adding, editing, deleting a task (editing and deleting assigned tasks may be prohibited)
* student: browsing task list, viewing task details
* student (without teams): selecting a task
* student (in team mode): see current teams(at least incomplete), create team for a task, apply for team membership

==== Grading ====
This is an evolved grading page (submission.php), for teachers use.

New abilities:
* the table will reflect a status of task (maybe with icons)
* individual tasks: the table will additionally reflect task name (as a link to popup with it's description) and a grade factor
* teams: the table (and popup for grading too) will have two modes:
* teams and/or individual tasks: in case any form of teacher approvment is needed, columns for approvment will be showed
* grade columns/popus will be showed only when grading is allowed (or if person has mod/assignment:manageanything capability)
*# team grades - each string represent a team
*# individual grades - each string represents a student, but they are sorted by team and teams is spaced somehow
* make an option for the teachers to make any grade final, forbidding further re-submissions and/or regrading (a person with mod/assignment:manageanything can still regrade); in teams with individual grading mode re-submission will be forbidden only when all team members receive final grade
* dropdown to choose whom to display in the table (and in the popup): all, with submissions only, needs grading only

=== Capabilities ===
Current capabilities
* mod/poasassignment:view - actually quite strange capability that can completely block you from assignment
* mod/poasassignment:submit - ability to submit a work
* mod/poasassignment:grade - ability to grade submissions

New capabilities
* mod/poasassignment:viewownsubmission (can be backported to 1.9) - sometimes we need to not allowing the student to see own submission (exams cases mostly)
* mod/poasassignment:manageanything - person with high authority, for whom don't apply usual restrictions: he can edit/delete tasks on which people worked right now, manage group membership and their tasks after an approval, override final grades and so on
* mod/poasassignment:managetasks - ability to create, edit and delete tasks
* mod/poasassignment:managefields - ability to manage custom fields of tasks
* mod/poasassignment:finalgrades - can make grades final
* mod/poasassignment:manageteams - ability to create, force students to the team, approve students (teacher's ability)
* mod/poasassignment:managetaskselection - ability to manage tasks selection for any student (teacher's ability)
* mod/poasassignment:manageownteam - ability to create new team, apply to existing one, confirm memebership of the others in this team (student's ability, setting it to Deny will create an task where only teachers can manage teams membership)
* mod/poasassignment:selectowntask - student's ability to select task (setting to Deny allows for teachers-only tasks selection)
* mod/poasassignment:seeotherstasks - student's ability - if he/she is able to see what tasks are selected by other people, or he can see only if it free for selection

[[Category:Assignment]]

XHTML

2009-09-24T07:55:34Z

Josepuib: missing words added

==XHTML Strict 1.0==

Moodle output must be compliant with XHTML Strict 1.0. This means it must be:

===Well-formed XML===

In a well-formed XML document, every opening tag has a matching close tag; tags are properly nested, attributes are properly quoted, and the file contains no syntax errors. See [http://www.w3.org/TR/xml/#sec-well-formed the XML specification for a formal definition].

While developing, you should have the option Administration ► Server ► Debugging ► XML strict headers turned on. With this option on, your web browser will refuse to display any page that is not well-formed. This makes such problems easy to find and fix.

===Valid XHTML Strict===

This means that the XML of your page follows the particular rules from the [http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict XHTML-1.0-Strict DTD]. <nowiki>For example, the first tag in the file must be <html>, a <form> tag must have an action="" attribute, an <li> can only appear inside an <ol> or <ul>, you cannot use <frame> tags, and so on.</nowiki> and so on.

You can check whether the HTML you output is valid by using a HTML validator, for example the [https://addons.mozilla.org/en-US/firefox/addon/249 Html Validator] add-on for Firefox.

===Semantic markup===

That is, HTML tags should be used only to mark up the appropriate types of content. For example:
* tables should not be used for page layout, just to display tabular information,
* if something is a heading, it should be marked up using <h''n''> tags, for an appropriate ''n'',
* <nowiki>if something is a list, it should be marked up using <ol>, <ul> or <dl>,</nowiki>
* see [[Semantic HTML]] for further details

==Styling==

How the HTML is laid out should be controlled by CSS in whichever theme is currently selected.

* Ensure that the HTML contains enough id="..." and class="..." attributes so that theme designers can easily control how it is displayed.
* Never embed inline styles in the HTML (that is, do not use the style="..." attribute).
* As you change core Moodle code, you must update the standard theme so that Moodle looks OK out of the box.
* If you need to make basic style definitions for a module (or some other sorts of plugin), put them in a file called styles.php in that module. This will be included into every theme.

== Moodle API ==

* Use the functions in lib/weblib to do as much as possible (print_header(), print_box() etc)
* This API will change a lot in Moodle 2.0. See: [[Navigation_2.0]]

== See also: ==

* [http://developer.apple.com/internet/webcontent/bestwebdev.html Web Page Development: Best Practices] by the Safari development team at Apple.

XHTML

2009-09-24T07:53:26Z

Josepuib: missing word added

==XHTML Strict 1.0==

Moodle output must be compliant with XHTML Strict 1.0. This means it must be:

===Well-formed XML===

In a well-formed XML document, every opening tag has a matching close tag; tags are properly nested, attributes are properly quoted, and the file contains no syntax errors. See [http://www.w3.org/TR/xml/#sec-well-formed the XML specification for a formal definition].

While developing, you should have the option Administration ► Server ► Debugging ► XML strict headers turned on. With this option on, your web browser will refuse to display any page that is not well-formed. This makes such problems easy to find and fix.

===Valid XHTML Strict===

This means that the XML of your page follows the particular rules from the [http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict XHTML-1.0-Strict DTD]. <nowiki>For example, the first tag in the file must be <html>, a <form> tag must have an action="" attribute, an <li> can only appear inside an <ol> or <ul>, you cannot use <frame> tags, and so on.</nowiki> and so on.

You can check whether the HTML you output is valid by using a HTML validator, for example the [https://addons.mozilla.org/en-US/firefox/addon/249 Html Validator] add-on for Firefox.

===Semantic markup===

That is, HTML tags should be used only to mark up the appropriate types of content. For example:
* tables should not be used for page layout, just to display tabular information,
* if something is a heading, it should be marked up using <h''n''> tags, for an appropriate ''n'',
* <nowiki>if something is a list, it should be marked up using <ol>, <ul> or <dl>,</nowiki>
* see [[Semantic HTML]] for further details

==Styling==

How the HTML is laid out should be controlled by CSS in whichever theme is currently selected.

* Ensure that the HTML contains enough id="..." and class="..." attributes so that theme designers can easily control how
* Never embed inline styles in the HTML (that is, do not use the style="..." attribute).
* As you change core Moodle code, you must update the standard theme so that Moodle looks OK out of the box.
* If you need to make basic style definitions for a module (or some other sorts of plugin), put them in a file called styles.php in that module. This will be included into every theme.

== Moodle API ==

* Use the functions in lib/weblib to do as much as possible (print_header(), print_box() etc)
* This API will change a lot in Moodle 2.0. See: [[Navigation_2.0]]

== See also: ==

* [http://developer.apple.com/internet/webcontent/bestwebdev.html Web Page Development: Best Practices] by the Safari development team at Apple.

lib/formslib.php Usage

2009-09-23T07:22:34Z

Josepuib: spelling mistake

{{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 :

<code php>
require_once('pathtoformdescription');
//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);

}
</code>

===Defining Your Form Class===

The form class tells us about the structure of the form. You are encouraged to put this in a 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}_{function}_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 attribute 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()====

[[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 form often little changes need to be made in the post processing. 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]]

Blocks

2009-09-19T17:31:54Z

Josepuib: blank space deleted

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''reference''' text should refer to [[Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks#Eye_Candy| how to disable the title's display]].

[[Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:'''<br />
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: <span class="filename">/blocks/simplehtml/'''config_instance.html'''</span> (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:

<code php>
<tr valign="top">
<td align="right"><p>
<?php print_string('configtitle', 'block_simplehtml'); ?>:</p>
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return true;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file <span class="filename">/blocks/simplehtml/config_global.html</span> which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>
<p>
<input type="submit" value="<?php print_string('savechanges'); ?>" />
</p>
</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

===and some other useful examples too:===
<code php>
function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
</code>

This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.

If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

<code php>
function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
</code>

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' <br />
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== See also ==
[http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

XMLDB introduction

2009-09-16T12:19:51Z

Josepuib: spelling mistake

[[XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 years old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

SSH key

2009-08-27T12:41:05Z

Josepuib:

==What is a SSH key?==

SSH keys are used for secure connections across a network. They come in pairs, so you have a public key and a private key.

The standard ssh2 file format (see
http://www.openssh.org/txt/draft-ietf-secsh-publickeyfile-02.txt)
looks like this:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "jtbell@Jon-Bells-Computer"
AAAAB3NzaC1kc3MAAACBAPNgmidbM2rhYjUXunpnlXjHWfV+vc8/5YKrn8Y5P0Y6KwmG2G
GMgNBon3LX3iJlBhtuU3FCBj3G1Kdt5vUhQHhUmHVrOasi47vawTrv7ZJCfiaSGwRsiBHt
Jta5CAp7t0EnzX2q6BvPbFBBHNLyy6uNVpL2jOR06Pkx/vaqyScvAAAAFQDHvwmjWYwK9g
K6Sp+pSvI7bwEUtwAAAIANMJDotMpfj89N+7+FJylSS+uFEQSS61PxENl/Mcj1jUREjJg2
eNsJdAB9Ev99hWYS+7lFRtTJ2eh4Y9gpGe7BX3e2YGHOqp8cWCVCIKaMzwk9To+xnfThWq
IfHT8I6CJxp/5ez02m6F2k/5iukvOwbGms6EAZK1DTBhDOHjEQwQAAAIAlz2/qBWkaMP+s
W8FLmGKM+cCw5+asOaJGTwrFVuwJkDMvdEWxmG92A2dxuUske0d/AkN6zJp7HD0wlfesRM
3+c+Res5qun9lFcdM4i03VoV5mXd+T7laS8yku6vZgvZZFnPvr2LOUnc7XThGFwMaQpFEW
U8cvQbttO6QrT2CD2w==
---- END SSH2 PUBLIC KEY ----

However, Moodle uses OpenSSH on its server and this key will not work with the OpenSSH server in this format; OpenSSH requires the key to be in OpenSSH format. Here is an example of a DSA public key in OpenSSH format (usually they are all in one line):

ssh-dss AAAAB3NzaC1kc3MAAACBAJ3hB5SAF6mBXPlZlRoJEZi0KSIN+NU2iGiaXZXi9CDrgVxTp6/
sc56UcYCp4qjfrZ2G3+6PWbxYso4P4YyUC+61RU5KPy4EcTJske3O+aNvec/20cW7PT3TvH1+sxwGry
mD50kTiXDgo5nXdqFvibgM61WW2DGTKlEUsZys0njRAAAAFQDs7ukaTGJlZdeznwFUAttTH9LrwwAAA
IAMm4sLCdvvBx9WPkvWDX0OIXSteCYckiQxesOfPvz26FfYxuTG/2dljDlalC+kYG05C1NEcmZWSNES
GBGfccSYSfI3Y5ahSVUhOC2LMO3JNjVyYUnOM/iyhzrnRfQoWO9GFMaugq0jBMlhZA4UO26yJqJ+BtX
IyItaEEJdc/ghIwAAAIBFeCZynstlbBjP648+mDKIvzNSS+JYr5klGxS3q8A56NPcYhDMxGn7h1DKbb
2AV4pO6y+6hDrWo3UT4dLVuzK01trwp PYp6JXTSZZ12ZaXNPz7sX9/z6pzMqhX4UEfjVsLcuF+ZS6a
QCPO0ZZEa1z+EEIZSD/ykLQsDwPxGjPBqw== someone@somewhere.com

In addition to OpenSSH and Standard SSH formats there are a variety of proprietary formats as well as SSH1 and SSH2 differences to account for, which can make this confusing.

In the example above you will note that the key starts with "ssh-dss". This is because this key was generated using DSA as opposed to RSA. A number of vendors in the SSH arena have argued, as per the PuTTY documentation that can be found at http://the.earth.li/~sgtatham/putty/0.55/htmldoc/Chapter8.html#S8.2.10 that users should employ RSA encryption because

DSA has an intrinsic weakness which makes it very easy to create a signature
which contains enough information to give away the private key! This would
allow an attacker to pretend to be you for any number of future sessions.

An SSH2 public key in OpenSSH format will start with "ssh-rsa".

The idea behind all of this is that once you have keys on the remote server and your local host, access will be simpler since the server will only grant access to someone who has the matching private key.

==Why do I need a SSH key?==

Our CVS server uses OpenSSH, so if you are a Moodle developer and you want to make your logins easier (by avoiding typing in your password all the time) then you will need to submit public key in Openssh format via the "Update my developer information" tab at http://moodle.org/cvs.

==How do I create a SSH key pair?==

===Platform Independent===

Visit http://www.sshkeygen.com and simply follow the directions there.

===Eclipse===

If you plan to use Eclipse for development, please refer to the Eclipse document https://docs.moodle.org/en/Eclipse as Eclipse now has a plugin that allows you to manage all ssh key matters from within Eclipse.

===Unix/Linux===

You can use ssh-keygen at your system prompt. Please consult the man page on your system for the options available to you.

# Run: '''ssh-keygen -t (rsa or dsa)'''. This will not include a passphrase. *
# Use of rsa or dsa above will result in rsa or dsa replacing each XXX below.
# Look in your ~/.ssh directory (or wherever you saved the output). You'll find '''id_XXX''' (private) and '''id_XXX.pub''' (public).
# Cut and paste the contents of '''id_XXX.pub''' into your developer profile on http://moodle.org/cvs
# Put the private key wherever you will be calling CVS from (in your .ssh directory, for example). Make sure it's secure!

* This section initially recommended using ''ssh-keygen -d'' but it is unclear what the source of this -d option might be.

===Windows===
Use puttygen and follow the instructions [http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter8.html here]. Make sure you choose the RSA2 key format and that when you copy the key data into the textbox on the site, that you have all of the characters on one line. If you have opened the key with word pad, it will have line breaks in it which will stop it from working.

The box should look like this:

ssh-rsa
AAAAWfg&jkf4D34H5@4svf..... (single very long line continues beyond edge of textbox)

===Mac OS X===

XHTML

2009-08-26T10:19:54Z

Josepuib:

==XHTML Strict 1.0==

Moodle output must be compliant with XHTML Strict 1.0. This means it must be:

===Well-formed XML===

In a well-formed XML document, every opening tag has a matching close tag; tags are properly nested, attributes are properly quoted, and the file contains no syntax errors. See [http://www.w3.org/TR/xml/#sec-well-formed the XML specification for a formal definition].

While developing, you should have the option Administration ► Server ► Debugging ► XML strict headers turned on. With this option on, your web browser will refuse to display any page that is not well-formed. This makes such problems easy to find and fix.

===Valid XHTML Strict===

This means that the XML of your page follows the particular rules from the [http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict XHTML-1.0-Strict DTD]. <nowiki>For example, the first tag in the file must be <html>, a <form> tag must have an action="" attribute, an <li> can only appear inside an <ol> or <ul>, you cannot use <frame> tags, and so on.</nowiki> and so on.

You can check whether the HTML you output is valid by using a HTML validator, for example the [https://addons.mozilla.org/en-US/firefox/addon/249 Html Validator] add-on for Firefox.

===Semantic markup===

That is, HTML tags should be used only to mark up the appropriate types of content. For example:
* tables should not be used for page layout, just to display tabular information,
* if something is a heading, it should be marked up using <h''n''> tags, for an appropriate ''n'',
* <nowiki>if something is a list, it should marked up using <ol>, <ul> or <dl>,</nowiki>
* see [[Semantic HTML]] for further details

==Styling==

How the HTML is laid out should be controlled by CSS in whichever theme is currently selected.

* Ensure that the HTML contains enough id="..." and class="..." attributes so that theme designers can easily control how
* Never embed inline styles in the HTML (that is, do not use the style="..." attribute).
* As you change core Moodle code, you must update the standard theme so that Moodle looks OK out of the box.
* If you need to make basic style definitions for a module (or some other sorts of plugin), put them in a file called styles.php in that module. This will be included into every theme.

== Moodle API ==

* Use the functions in lib/weblib to do as much as possible (print_header(), print_box() etc)
* This API will change a lot in Moodle 2.0. See: [[Navigation_2.0]]

== See also: ==

* [http://developer.apple.com/internet/webcontent/bestwebdev.html Web Page Development: Best Practices] by the Safari development team at Apple.

Coding

2009-08-25T21:50:49Z

Josepuib:

This page is the top-level page describing Moodle's coding guidelines. It's the place to start if you want to know how to write code for Moodle.

<p class="note">WARNING: Under construction RIGHT NOW!</p>

==Moodle architecture==

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see: [[Moodle architecture]].

==Plugins==

Moodle has a general philosophy of modularity. There are over 25 different types of plugins, however many of these plugin types work the same way.

For more about the structure of plugins, see [[Plugins|Moodle plugins]].

==Coding style==

Consistent coding style is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our [[Coding_style|Moodle coding style]] document explains this standard.

==Security==

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Security|Moodle security guidelines]].

==XHTML==

It's important that Moodle produces strict, well-formed XHTML code, compliant with all common accessibility guidelines (such as W3C WAG).

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

Full information is here: [[XHTML|Moodle XHTML]]

==JavaScript==

In general, everything in Moodle should work with JavaScript turned off in your browser. If you do have JavaScript enabled it should only improve usability (not add features).

This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.

See the [[JavaScript guidelines|Moodle JavaScript guidelines]] for more information.

==Internationalisation==

Moodle works in over 81 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code and documentation, however, is English (AU).

Full details: [[Internationalisation|Moodle Internationalisation]]

==Accessibility==

Moodle should work well for the widest possible range of people.

See: [[Accessibility|Moodle Accessibility]]

==Usability==

See: [[Moodle_User_Interface_Guidelines|Moodle User Interface Guidelines]] (being produced summer 2009)
* Implementing user interfaces: [[Interface_guidelines| Interface Guidelines]]

==Database==

Moodle has a powerful database abstraction layer that we wrote ourselves, called [[XMLDB_Documentation|XMLDB]]. This lets the same Moodle code work on MySQL, PostgreSQL, Oracle and MSSQL.

We have tools and API for [[DDL functions|defining and modifying tables]] as well as [[DML functions|methods for getting data in and out]] of the database.

Overview: [[Database|Moodle Database]] guidelines

==Events==

Moodle allows inter-module communication via '''events'''. Modules can '''trigger''' specific events and other modules can choose to '''handle''' those events.

Full information: [[Events_API|Moodle Events API]]

==Unit tests==

[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a library called simpletest (not very extensively yet though!) that makes writing unit tests fairly simple. Our unit testing is currently not deep but we want to improve this.

Full information here: [[Unit_tests|Moodle Unit Tests]]

== See also ==
* [http://doku.clausvb.de/php_coding_standard.htm General PHP coding standards]
* [http://pear.php.net/manual/en/standards.php PEAR coding standards]

[[Category:Coding]]

[[es:Manual de Estilo de Código]]
[[ja:コーディング]]
[[zh:代码指南]]
[[pl:Kodowanie]]
[[pt:manual_de_codigo]]
[[fr:Développement:Directives_de_codage]]