MoodleDocs - User contributions [en]

Upgrading to Moodle 1.9

2008-10-09T13:31:17Z

Hccrle: /* Upgrading more than one version */ correct grammar

{{Moodle 1.9}}
==Before upgrading, please...==

* Check that your site meets all system requirements for 1.9 in ''Administration > Server > [[Environment]]''
* Do a full database backup!
* Remember to purge PHP cache if using any PHP accelerator
* Read [[Upgrading to Moodle 1.8]] if you are upgrading to 1.9 from 1.6 or 1.7
* Read [[Upgrading to Moodle 1.7]] if you are upgrading from 1.6

===Notes===
* If upgrading from 1.6 or later, you must have converted your site to Unicode
* If upgrading from earlier than 1.6, we recommend upgrading to 1.6 first, then 1.8 -> 1.9
* We recommend PHP 5.2 or later, but you must have at least PHP 4.3.0

==Now upgrade==

Once you have satisfied the requirements for Moodle 1.9, follow the instructions on the [[Upgrading|upgrading]] page.

==Upgrading more than one version==

In general, it is recommended to upgrade via each version of Moodle, for example 1.7 -> 1.8 -> 1.9. An exception to this is when upgrading from 1.5 or 1.6, when it is recommended that 1.7 be skipped, in other words upgrade 1.5 -> 1.6 -> 1.8 -> 1.9. (The main reason for this recommendation is that the default roles settings obtained when upgrading to 1.7 are not ideal for 1.8 onwards.)

==Front page activities==

To enable logged-in users to participate in front page activities, such as viewing the site news, the default front page role should be set to student in ''Administration > Front Page > [[Front Page settings]]''.

== Gradebook ==

=== What improvements in the gradebook justify upgrading from 1.8 to 1.9? ===
*Faster execution, more noticeable with large sites
*More scalable
*More control over the display of grades, to teachers and students
*More [[Category aggregation|aggregation options]]
*A simple, [[Development:Grades#API_for_communication_with_modules.2Fblocks|public API]] that can be used by any module to support grading
*Possibility to write [[Development:Gradebook_Report_Tutorial|custom grade reports]]
*A [[Development:Grades#History_tables|"Grade change history" record]]

=== Why is the new gradebook so complicated? ===
Added power and control requires more options. It is mostly the number of options and settings that gives the impression of complexity. Here are some of the main reasons for the changes made in the gradebook for 1.9:

*Previous gradebook did not scale well: it became very slow and unmanageable in large organisations with many students, activities and grades
*Grades were generated and stored by each module without much consistency
*Difficulty in producing new types of reports
*No [[Outcomes]]

=== Is the gradebook in 1.9 faster than in 1.8? ===
According to [http://moodle.org/mod/forum/discuss.php?d=91034&parent=410224 one early report], yes. There are other more thorough benchmark tests being conducted, and we will publish the results when they are made public.

==See also==

*[[Release Notes]]
*[[:Category:Moodle 1.9]]
*[[Question Engine Changes in Moodle 1.9]] (includes some important documentation on question engine upgrade for those who make extensive use of the question bank and quiz module)
Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=75088 Automatic update of language package while updating in 1.9]
*[http://moodle.org/mod/forum/discuss.php?d=89825 Change in Moodle 1.8 and 1.9 : admin tree icons are now themeable - some themes need to be upgraded]
*[http://moodle.org/mod/forum/discuss.php?d=92027 Migration 1.8 to 1.9]

[[Category:Installation]]

[[fr:Mise à jour à Moodle 1.9]]
[[ja:Moodle1.9へのアップグレード]]

XMLDB introduction

2007-08-29T10:53:08Z

Hccrle: /* The process */ grammar corrections

[[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 be filled following the next 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 part developers to migrate along the time 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, but 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 in an high degree.

* '''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 underlying RDBMS. It will help us to 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 in 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, independently of the underlying RDBMS being used. And this must be particularly true for the XMLDB part. Point.

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 an 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''' continues 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 this situation 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 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 chuncks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending following some easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprensive 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

2007-08-28T11:22:46Z

Hccrle: /* The Stack */ correct grammar: this libraries -> these libraries, request -> requests

[[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 be filled following the next 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 part developers to migrate along the time 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, but 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 in an high degree.

* '''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 underlying RDBMS. It will help us to 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 in 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, independently of the underlying RDBMS being used. And this must be particularly true for the XMLDB part. Point.

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 an 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''' continues 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 this situation 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 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 splitted in small chuncks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending following some easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprensive list of issues that need to be determined/solved prior to incorporate them to 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数据库计划]]

Output functions

2007-07-18T10:27:35Z

Hccrle: /* print_textarea() */ correct grammar (tense agreement)

This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!

Of course, these functions can be discussed, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].

For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!

=== p() and s() ===

function s($var, $strip=false)
function p($var, $strip=false)

These functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

These functions should be used to:

* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
* to '''show plain (non html) text''' that has been introduced by the user (search string, quiz responses...).
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

It is important not to use these functions for strings that contain html markup.

The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.

The key parameter for this function is:

* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

=== format_text() ===

function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )

This function should be used to:

* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...

Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

Some interesting parameters for this function are:

* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. See [[Formatting options]].

* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true ever''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for FORMAT_PLAIN, the text is never cleaned.
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true). This is ignored by FORMAT_PLAIN for which smileys are never converted.
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== format_string() ===

function format_string ($string, $striplinks = false, $courseid=NULL )

This function should be used to:

* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).

Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of its options or protections'''. It simply filters the strings and returns the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.

Some interesting parameters for this function are:

* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result text. Used when we want to show the text inside menus, page titles... (defaults to false).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== print_textarea() ===

function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)

This function should be used to:

* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

Some interesting parameters for this function are:

* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
* '''rows, cols''': to be applied it the standard textarea is showed.
* '''width, height''': to be applied if the HTML editor is used.
* '''name''': the name of the field that will contain the text once the form is submitted.
* '''value''': the initial value of the textarea.
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

[[Category:Output functions]]

Output functions

2007-07-17T18:12:56Z

Hccrle: /* format_string() */ corrected grammatical errors

This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!

Of course, these functions can be discussed, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].

For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!

=== p() and s() ===

function s($var, $strip=false)
function p($var, $strip=false)

These functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

These functions should be used to:

* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
* to '''show plain (non html) text''' that has been introduced by the user (search string, quiz responses...).
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

It is important not to use these functions for strings that contain html markup.

The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.

The key parameter for this function is:

* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

=== format_text() ===

function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )

This function should be used to:

* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...

Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

Some interesting parameters for this function are:

* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. See [[Formatting options]].

* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true ever''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for FORMAT_PLAIN, the text is never cleaned.
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true). This is ignored by FORMAT_PLAIN for which smileys are never converted.
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== format_string() ===

function format_string ($string, $striplinks = false, $courseid=NULL )

This function should be used to:

* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).

Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of its options or protections'''. It simply filters the strings and returns the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.

Some interesting parameters for this function are:

* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result text. Used when we want to show the text inside menus, page titles... (defaults to false).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== print_textarea() ===

function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)

This function should be used to:

* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

Some interesting parameters for this function are:

* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
* '''rows, cols''': to be applied it the standard textarea is showed.
* '''width, height''': to be applied if the HTML editor is used.
* '''name''': the name of the field that will contain the text once the form was submitted.
* '''value''': the initial value of the textarea.
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

[[Category:Output functions]]

Output functions

2007-07-17T18:06:38Z

Hccrle: /* format_text() */ removed double negative (never -> ever)

This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.

By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!

Of course, these functions can be discussed, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].

For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!

=== p() and s() ===

function s($var, $strip=false)
function p($var, $strip=false)

These functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.

These functions should be used to:

* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.
* to '''show plain (non html) text''' that has been introduced by the user (search string, quiz responses...).
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters

It is important not to use these functions for strings that contain html markup.

The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.

The key parameter for this function is:

* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).

=== format_text() ===

function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL )

This function should be used to:

* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...

Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.

Some interesting parameters for this function are:

* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOWN. See [[Formatting options]].

* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true ever''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for FORMAT_PLAIN, the text is never cleaned.
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true). This is ignored by FORMAT_PLAIN for which smileys are never converted.
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== format_string() ===

function format_string ($string, $striplinks = false, $courseid=NULL )

This function should be used to:

* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).

Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of it options nor protections'''. It simply filters the strings and return the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.

Some interesting parameters for this function are:

* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result test. Used when we want to show the text inside menus, page titles... (defaults to false).
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.

=== print_textarea() ===

function print_textarea($usehtmleditor, $rows, $cols, $width,
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)

This function should be used to:

* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.

Some interesting parameters for this function are:

* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.
* '''rows, cols''': to be applied it the standard textarea is showed.
* '''width, height''': to be applied if the HTML editor is used.
* '''name''': the name of the field that will contain the text once the form was submitted.
* '''value''': the initial value of the textarea.
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.

[[Category:Output functions]]