MoodleDocs - User contributions [en]

Question engine

2010-12-23T13:24:53Z

Ganderson: /* Questions */ Add Wikipedia link to define the term QTI

{{Template:Question development}}

Moodle has a powerful question engine with a modular structure to allow question type plug-ins. The question engine is responsible for rendering the questions and for processing student responses. It is used by the [[Quiz developer docs|quiz module]] and it is planned that in future it will be used by the Lesson and other modules.

Historically the question engine started as a part of the quiz module. Only since Moodle 1.6 is it a separate core component of Moodle that can be used by any other Moodle component or module. During this restructuring the code was moved from mod/quiz/ to question/ and the tables and functions were renamed. Wherever the old table or function name contained 'quiz_' the new one will contain 'question_'

==Terminology==

When talking about the question engine there are certain terms that can cause confusion because they can be used with different meanings. In Moodle we have adopted a certain terminology that will be explained below.

===Questions===

A '''question''' is the set of definitions (question name, question text, possible answers, grading rules, feedback, etc.) that constitute a reusable assessment item. So it includes much more than what one would in everyday language call a question.
In the terminology of the [http://en.wikipedia.org/wiki/QTI QTI] specification a 'question' is more appropriately called an '''assessment item''' or just 'item' for short.

There are different types of questions, like for example multiple-choice questions or numerical questions. These are referred to as '''[[Question engine#Question types|question types]]''' in Moodle.

Since version 1.5 Moodle is able to handle so-called '''[[Adaptive questions]]''', also known as 'adaptive items' in QTI speak. These are questions that interact with the student by going through several states depending on the student responses. For example a complicated mathematical question that is answered incorrectly, but is likely to be incorrect because of a common mistake, could provide the user with a hint towards this mistake, apply a penalty and allow a second attempt at this question. Quizzes can be run in 'adaptive mode', in which case Moodle provides buttons to mark each question individually.

===Answers===

In Moodle the term ''''answer'''' is used exclusively for the '''teacher-defined answers''' of a question. It is easy to get confused between these teacher-defined answers and the answers that the students actually give. We have therefore adopted the convention to refer to the student-supplied answers as 'responses' and to reserve the term 'answers' to apply to teacher-defined answers. In question types that rely on teacher-supplied answers these are used in the grading process by comparing them with the student responses. Of course not all question types use teacher-defined answers but use some more intelligent way to process the student responses.

Perhaps one should also stress that 'answer' is not always used in the sense of 'correct answer'. For example every choice in a multiple-choice question is referred to as an answer. Other systems use the term 'distractor' for wrong answers.

In Moodle we always use the term ''''responses'''' to refer to the students' responses to a question. This term is always used in plural, although for some questiontypes there is only one possible response.

There is unfortunately, for historical reasons, one exception to the above rule: The question_states table has a field 'answer' whose purpose it actually is to hold the student's responses.

===Attempts===

In Moodle the term ''''attempt'''' is used in the sense of "Attempt at a quiz" (or another activity involving questions). Depending on the quiz settings, a student may be allowed several attempts at a quiz. An attempt is finished when the student clicks on the corresponding button on the attempt page. Students do not have to complete an attempt in one visit. They can navigate away from the quiz page and return later to continue the same attempt.

Each module that uses the question engine should hold its own data for the attempts in its own tables. When the module calls the question engine functions it is often expected to pass an attempt object.

Within one and the same quiz attempt a student may make several attempts at answering a particular question, at least if the questiontype allows it and the quiz is set up in adaptive mode. These will always be referred to as ''''question sessions'''' or sometimes 'attempts at a question, never just as 'attempts'.

===Sessions, States, Events===

When a new attempt is started, a new '''session''' is started for each question. So in a sense a session is for a question what an attempt is for a whole quiz. A question session lasts no longer than an attempt and for each question there can only by one session within one attempt.

Moodle allows the student to interact with a question repeatedly within one session and each such interaction leads to a new '''state'''. The first state is created when the session is created. A new state is then created when a student saves, validates or submits an answer or .... The student's responses and, if appropriate, the results of response processing (grading) are stored in the new state that gets created.

The type of '''event''' that led to the creation of a particular state is saved along with the state. The types of events currently used are:
;open :A new session has just been created and this is the opening state. Usually it doesn't hold student responses yet (except where a quiz attempt is based on a previous attempt because the 'attemptonlast' option is set).
;save:The student has clicked the save button.
;validate:The student has asked for his responses to be validated. This means it is checked that they are valid responses. In the case of mathematical questions which requires the input of a mathematical expression in some linear format the question type may want to display the validated result back to the student in typeset form. Similar things may apply to other subject-specific question types. If a student response is found to be invalid the student is told so but no penalty is applied. The invalid response is stored with the state.
;grade:The student has pressed the submit button. The grade is calculated and stored with the attempt.
;duplicategrade:The student has pressed the submit button but the response to this question has not actually changed. This happens a lot in quizzes with several questions on one page where the student may have changed the responses for one question only. I believe that states created by this type of event are not stored in the database.
;close:The last state in a session which is now closed. Currently a session closes only when the attempt closes, either because the student requests it or because the timelimit elapses.

There are now plans to introduce another event type
;submit:The student has submitted his responses for grading but grading has not yet taken place. This will be used by teacher-marked question types like the essay questions for example.

==Code documentation==

The code is documented according to [http://www.phpdoc.org/ PHPdocumentor] conventions. The explanations here in the wiki are meant to complement this.

Inline comments should be used liberally in the code. The following conventions make it easier to search for comments with special meaning:
* use TODO in comments about things that need to be done
* use ??? in comments that are questions about the code

Code is organised into packages
* Package questionbank - code that relates to the questionbank system
** Subpackage questiontypes - code that relates to the question types, including the question type base class.
** Subpackage importexport - code that relates to importing and exporting questions.

Generally, the base classes default_questiontype and qformat_default should contain most of the documentation, since all question types should follow the same interface. There is no value in repeating the same information on all the various subclasses. The subclasses should concentrate on describing any new methods they have that do not come from the base class.

See the [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html#coding.phpcomments PHPdocumentor manual] for more advice on writing good comments.

Moodle PHPdocs can be seen here: http://phpdocs.moodle.org/.

==API==

The library lib/questionlib.php contains all functions that need to be available to any module wanting to use questions (this is new in Moodle 1.6, in Moodle 1.5 this was part of mod/quiz/locallib.php). Loading this library instantiates all questiontype classes by loading the questiontype.php files

A description of the API still needs to be written. Also lib/questionlib.php should be cleaned up a bit to distinguish between the API functions and the helper functions.

==Organisation==
The default questiontype class is defined in '''question/type/questiontype.php''' (in Moodle 1.5 this was still in mod/quiz/locallib.php). The individual questiontypes extend this class in their own questiontype.php file. For documentation of the questiontype classes one should often look at the documentation of the default question type because much of the documentation that is in the default class is not repeated in the other questiontype classes.

While questiontypes are realized as classes, the question engine is not written in a truly object-oriented way. Instead it follows the Moodle model of using objects mostly only as alternatives to arrays to hold database records. So none of the question, attempt, and state objects that play a central role in the module have any methods. Only the questiontype objects have methods. Strangely enough the quiz module instantiates one object of each questiontype class at the start and then reuses their methods for the different questions. If one is used to the Moodle way of programming then this is easy enough to handle.

==Objects and data structures==

Key to understanding how the question engine works is to understand how the different kinds of object work together. The most important ones are:

*Questions
*Attempts
*States

Questions are data created by the teacher. Attempts and States are data created by the student when interacting with a quiz.

The Moodle quiz module allows students to make several attempts at a quiz. Data about such an '''attempt''' is stored in an attempt object. The Moodle question engine was optimized to deal with such attempts and therefore every module wanting to use the question engine also has to implement the attempt object and pass it to many of the question engine functions. The attempt object holds for example information about how the quiz was randomized for this attempt and the ordering of the questions and answers.

Moodle allows students to interact repeatedly with a single question. So for example the student might initially just save an answer, later mark it, then correct it if it was marked incorrect. When the student first views a question within a particular attempt a '''question session''' and the first question state is created. Each time the student interacts with the question a new '''question state''' is created. So states are indexed by user id, attempt id and question id.

===Database structure===
All this data needs to be kept in Moodle's database. How this is achieved is explained on a separate page about the '''[[Quiz database structure]]''', which also contains a useful diagram.

As is customary in Moodle, most runtime objects simply represent the data from a particular database record. So for example a $quiz object has fields corresponding to all the fields in the [[Quiz database structure#quiz|quiz table]]. In some cases the objects have some additional fields that are added at runtime. This is particularly the case for $question and $state objects. These additional fields are also described on the page about the '''[[Quiz database structure]]'''. Many functions that are used to process these objects make use of the additional fields and it is therefore necessary to use the correct functions for creating these objects.

===Runtime objects===
Some objects used by the quiz module are purely runtime object and do not correspond to a database table. The structure of these objects is explained in detail on a separate page about the '''[[Quiz runtime objects]]'''.

The main script of the quiz module is attempt.php which will have to deal with all these objects. Studying the '''[[Quiz attempt|explanation of attempt.php]]''' is therefore a good way to start to study the quiz module code.

==Response storage==

The student's responses to a question are stored in <code>$state->responses</code>. Questiontypes are completely free to implement the storage mechanism of their responses (and other state information) the way they want. Still, the standard questiontypes all follow a similar model. The default storage model and the questiontype specific variations are explained below.

The flexibility for the questiontypes to choose their response storage mechanism freely and to convert from the storage model to the runtime model is provided by a set of three functions, which allow to initialise the runtime <code>$state->responses</code> field, to convert from the runtime to the storage model and vice versa:

;<code>create_session_and_responses()</code>
:Initializes the $state object, in particular the <code>$state->responses</code> field

;<code>restore_session_and_responses()</code>
:Loads the question type specific session data from the database into the <code>$state</code> object, in particular it loads the responses that have been saved for the given <code>$state</code> into the <code>$state->responses</code> field.

;<code>save_session_and_responses()</code>
:Saves the question type specific session data from the $state object to the database. In particular, for most questiontypes, it saves the responses from the <code>$state->responses</code> to the database.

The generic quiz module code saves the contents form the <code><nowiki>$state->responses['']</nowiki></code> field to the answer field in the [[Quiz database structure#quiz_states|quiz_states table]] and also automatically restores the contents of this field to <code><nowiki>$state->responses['']</nowiki></code>. This means that any questiontype, which only expects a single value as its response can skip the implementation of the three methods described above. All questiontypes that have multiple value responses need to implement these methods.

The default questiontypes handle this problem by serializing/de-serializing the responses to/from the answer field in the quiz_states table. However, it is also possible (and may be better practice) to extend the quiz_states table with a questiontype specific table, i.e. take the id of the quiz_states record as a foreign key in the questiontype specific table. Because the value of <code><nowiki>$state->responses['']</nowiki></code> is set to the value of the answer field, questiontypes that serialize their response need to overwrite (in <code>save_session_and_responses()</code>) whatever value the generic code set this field to with their serialized value (usually achieved with a simple set_field).

In the method <code>restore_session_and_responses()</code> the serialized value can be read from <code><nowiki>$state->responses['']</nowiki></code> because this is where the value from answer field of the quiz_states table has been moved. Care needs to be taken that this array value is then unset or the whole array overwritten, so that the array does not accidentally contain a value with the empty string index.

==Response processing==

The runtime model for responses dictates the structure of the $state->responses array. Starting with the names of the form elements this section goes through the relevant processing steps and thus attempts to clarify why the keys of the $state->responses array can differ for different questiontypes; even more, it explains how the array keys are chosen and set.

Although it may initially seem strange to start with the naming convention of the form fields, the reason for this will become clear later on. The controls (i.e. the form fields) of a question get printed by the method <code>print_question_formulation_and_controls()</code>. The convention only dictates that the name of the control element(s) must begin with the value of <code>$question->name_prefix</code>. The <code>$question->name_prefix</code> is a string starting with "resp" followed by the question id and an underscore, e.g. <code>resp56_</code>. In the default case, when there is only a single control element (this includes the case of a list of equally named radio buttons), no postfix is appended to the name prefix. For questiontypes that allow or require multiple form elements, an arbitrary string can be appended to the name prefix to form the name of these form elements. The postfix must not include any relational data (i.e. ids of records in the quiz_answers table), because this can lead to problems with regrading of versioned questions.

After the printing of the question the server only sees it again when it is submitted. So the submitted data will contain several values indexed by strings starting with <code>respXX_</code>. Upon submission, the function <code>quiz_process_responses()</code> is called, which assigns the submitted responses to the state of the question with id XX, using the postfix (i.e. everything after the underscore) as array keys. In the default case with only one control element the name only consists of the name prefix. This explains why the default index of the <code>$state->responses</code> array is the empty string. The value of each array element is obviously the value that was submitted by the form, basically a raw response.

The function <code>quiz_process_responses()</code> in turn calls the questiontype specific method <code>grade_responses()</code> to assign a grade to the submitted responses and <code>compare_responses()</code> to determine whether the response was identical to the previous submission and to avoid regrading the same responses repeatedly. These questiontype specific functions need to be aware of the expected keys of the <code>$state->responses</code> array.

Finally, the methods <code>restore_session_and_responses()</code> and <code>save_session_and_responses()</code> also need to know the questiontype specific layout of the <code>$state->responses array</code> and restore or save the information, e.g. by converting from or to the data representation.

==Question types==
{{Questiontype developer docs}}
The quiz module is itself modular and allows question type plug-ins. For each question type there should be a page, accessible via the menu at the right, which provides at least the details about
*Database tables
*Response storage
*Question options object
*State options object
[[Question type code flow]]

It is hoped that Moodlers will contribute a lot of non-core question types in the future. For this it would be good to start a [[How to write a question type plugin]].

==Grades==

The handling of grades is a bit complicated because there are so many different grades around that get rescaled and combined in various ways. This section should summarize how this is done and why.

The following grade fields are being used:
*$question->defaultgrade
::This is the default value for the maximum grade for this question. This is set up when the teacher creates the question and it is stored in an int(10) field in the [[Quiz database structure#quiz_questions|quiz_questions]] table. However when the question is actually used in a particular quiz the teacher can overrule this default and this is stored in:
*$question->maxgrade
::This is the maximum grade that the teacher has assigned to this question in the context of the current quiz. This is by default equal to $questions->defaultgrade but the teacher can change this when editing the quiz. In the database it is stored in an int(10) field in the [[Quiz database structure#quiz_question_instances|quiz_question_instances table]].
*$question->penalty

*$state->raw_grade
*$state->grade
*$state->penalty
*$state->sumpenalty

*$attempt->sumgrades

The maximum grades set by the teacher, $question->defaultgrade and $question->maxgrade, are integers. All student-obtained grades are in principle floating point numbers. For historical reasons they are stored in the database as varchar(10) fields. Care has to be taken when writing to the database to make sure all grades are correctly rounded and squeezed into a string of no more than 10 characters, otherwise the writing to database will fail, see bug 4220.

The final outcome of the calculation of the grade for a user at a particular quiz is stored in the 'grade' field of the [[Quiz database structure#quiz_grades|quiz_grades table]]. This field has type double.

==Penalty mechanism==

===What it is for===

When the quiz is run in adaptive mode the student can interact with a question repeatedly. So in particular the student can try again when he gets a wrong answer. Clearly the final mark for the question must reflect the fact that the student did not get it right originally. Therefore a penalty is subtracted from the final mark.

===How the penalty is determined===

First of all penalties are relevant only if a quiz is run in adaptive mode. Only in this case can a student have a second attempt and therefore only in this mode can there be any occasion to subtract a penalty.

Even in adaptive mode the penalty mechanism is only used when it is selected in the quiz options. If "Apply penalties" is set to "No" then the final mark for the question is the mark for the last graded response.

Each question has a 'penalty' field (which should really be called 'penaltyfactor') which is a number between 0 and 1. The penalty for a wrong response is calculated as the product ($quiz->penalty * $quiz->grade), i.e., as the product of the penaltyfactor with the maximum achievable grade for the question. This product is stored in $state->penalty. So $quiz->penalty is the fraction of the maximum grade that is subtracted as a penalty for each wrong response.

The $quiz->penalty field has a default value of 0.1, both in the database and in mod/quiz/defaults.php. This default can of course be overwritten by the admin on the quiz configuration page. This admin-selected default is (as usual for admin defaults) stored in $CFG->quiz_penalty. The teacher can choose a different penalty factor for each individual question when adding or editing a question. (In Moodle 1.8 the default value of 0.1 is actually hardcoded at line 87 of moodle/question/type/edit_question_form.php)

Now if a student makes repeated wrong attempts (or partially correct attempts) the penalties for all these attempts are added up in $state->sumpenalties. The mark for the question is then calculated as the mark for the last graded response minus the sum of the penalties.

One curious fact about $state->sumpenalties is that, for efficiency reasons, it is not stored in the quiz_states table but instead in the 'sumpenalty' field of the quiz_newest_states table. That way it only has to be stored once per attempt rather than once per response.

===Where it is done in the code===

The function quiz_apply_penalty_and_timelimit() subtracts the penalty in $state->sumpenalty from the raw grade in $state->raw_grade to obtain $state->grade for the response. However it is ensured that the grade of a new attempt at the question never falls below the previously achieved grade. This function also increases $state->sumpenalty by the amount in $state->penalty. The assumption is that $state->penalty has just been set appropriately by the code calling this function, e.g., quiz_process_responses.

==Files belonging to questions==

This talks about the situation in relation to the Moodle 2.0 file API.

===File areas===

There are various file areas associated with each question.

For example there is a file are 'questiontext', belonging to the 'question' core component, which stores any images or other embedded files used by the question text. There are also 'generalfeedback' and 'question_answer' file areas.

There may also be some file areas specific to each question type. For example the 'qtype_multichoice' component has a 'correctfeedback' file area (among others).

All these file areas belong to the context that is the context of $question->category.

===Serving files and access checks===

This is a bit complicated because, although the files belong to the question system or a particular question type, then whether the user should be able to see a particular file (for example an image in the general feedback) is influenced by whichever part of Moodle is using the question (for example the quiz module or question preview).

The easiest way to explain is probably to show the call-stack for determining whether a particular image is displayed, then you can go and read the code.

For the request .../pluginfile.php/123/question/questiontext/234/345/image.png for an impage in the questiontext of a question in a quiz attempt.

(here, 123 is the contextid, 234 if the attemptid (corresponding to question_attempts.id) and 345 is the questionid.)

# pluginfile.php
# question_pluginfile() ''in lib/questionlib.php''
# quiz_question_pluginfile() ''in mod/quiz/lib.php''
# quiz_attempt->check_file_access() ''in mod/quiz/attemptlib.php''
# question->check_file_access() ''in lib/questionlib.php''
# qtype_''whatever''->check_file_access() ''in question/type/whatever/quetsiontype.php''

If, instead, the question was appearing in the question preview pop-up window, the call stack would be

# pluginfile.php
# question_pluginfile() ''in lib/questionlib.php''
# '''question_preview_question_pluginfile()''' ''in question/previewlib.php''
# question->check_file_access() ''in lib/questionlib.php''
# qtype_''whatever''->check_file_access() ''in question/type/whatever/quetsiontype.php''

(the different bit is highlighted in bold).

If, instead, the image url was .../pluginfile.php/123/qtype_multichoice/correctfeedback/234/345/image.png, the call stack would be

# pluginfile.php
# '''qtype_multichoice_pluginfile()''' ''in question/type/multichoice/lib.php''
# question_pluginfile() ''in lib/questionlib.php''
# quiz_question_pluginfile() ''in mod/quiz/lib.php''
# quiz_attempt->check_file_access() ''in mod/quiz/attemptlib.php''
# question->check_file_access() ''in lib/questionlib.php''
# qtype_multichoice->check_file_access() ''in question/type/multichoice/quetsiontype.php''

Roughly speaking, qtype_whatever->check_file_access() takes the same $question, $state and $options objects as print_question_formulation_and_controls, so, for example, you can do the same permissions check when trying to access a file in the feedback as was done when deciding whether to display the feedback.

The quiz_question_pluginfile or question_preview_question_pluginfile functions are responsible for getting the right $question, $state, $options based on the $attemptid and $questionid in the URL. They also do some basic access checks.

All the other functions are really just about dispatching the request to the right place to be handled.

[[Category:Question engine]]
[[Category:Quiz]]

User:Gary Anderson

2010-05-17T12:28:26Z

Ganderson:

[[Image:GaryAndersonLava.jpg|thumb|Picture during South American travels]]

Gary Anderson is a native of Seattle, a graduate of the University of Washington with degrees in Math, Business Economics, and certification in history education. He has a Master's degree in Teaching from Seattle University. Before entering teaching in 1996, he was the General Manager of the largest computer store in the Pacific Northwest which sold a majority of Apple II and Macintosh computers to schools, businesses and individuals around the I-5 corridor. He was also president of a software company that specialized in network communications.

Teaching is the family business for Gary. Both of his parents are retired teachers, and his brother is the principal of a middle school and his sister is an elementary school teacher.

His research interest is in the technology of instruction, and in particular the effects on student achievement when they receive rapid feedback on their performance. He has designed a number of software projects in advancement of this effort. He is currently working on a Moodle activity based on the theory of [http://en.wikipedia.org/wiki/Spaced_repetition Spaced Repetition] and another activity that customizes Wikimedia software for use in secondary school education.

[[Image:GaryAndersonMoodleMaster.jpg|left|thumb|Moodle Master during Halloween]]

Gary is the head of the Math Department at Seattle Academy and wonderful private, college prep, independent school that among many other things is in the 12th year of a universal laptop program for it's upper school. He teaches Advance Algebra, Second Year Calculus, and elective trimesters in Statistics, Math Modeling and Software Development. These math electives are the most popular electives in the school.

For the past 4 years, Gary has been known as the Moodle Master and has customized the software to make it especially usable in the high school environment (see [[Seattle_Academy]]). He is now turning over this day-to-day responsibility to has technology department and Curriculum Technology Coordinator Vicki Butler so the he can focus on being more involved in the larger technology community, contributing what he has learned from overseeing the school's Moodle project and other educational technology initiatives.

----
I will use subpages of my talk area to make more detailed observations and analysis of current Moodle issues that may not work well in the tracker, the forums, or other areas of Moodle's documentation.

# [[User_talk:Gary_Anderson/Extra credit status | Extra credit status]]
# [[User_talk:Gary_Anderson/Examples of Extra Credit grading | Examples of Extra Credit grading]]
# [[User:Gary_Anderson/1.9.8-2.0_update]]
----

User:Gary Anderson/1.9.8-2.0 update

2010-05-10T04:55:02Z

Ganderson: Steps to upgrade 1.9.9 to 2.0 preview 1

Seattle Academy has a very active Moodle 1.9 site with many custom extensions and potential legacy issues with it's database. I needed to do the following to update from the latest 1.9.8 to 2.0:

1. From the 1.9.8 backup, I deleted the wiki module. There were too many problems during update that prevented it from completing.

2. In version 2.0 preview 1, commented out line 61 of /mod/assignment/db/upgrade.php that begins $pbar->update. We have 750,000 assignment submissions. This line causes the browser doing updates to run out of memory at about 50,000 assignment submissions.

3. Comment out line 1936 of /lib/db/upgrade.php.

dbman->change_field_notnull($table, $field);

This was creating a fatal exception with our collection of blocks.

4. Change line 2612 of /lib/db/upgrade.php from $admins = get_admins(); to $admins = null. It was throwing an exception as it was not able to get_admins, perhaps since a login was not required (or permitted) to upgrade.

This allowed us to begin testing.

User talk:Gary Anderson

2009-05-20T12:56:01Z

Ganderson: Comment responded to...

== CVS with NetBeans ==

Hi Gary,
I have started to copy some of the instructions from your ''NetBeans for Moodle Development'' course to Moodle Docs ([[Development:Setting_up_Netbeans#CVS_with_NetBeans]]). Hope that's okay with you. --[[User:Frank Ralf|Frank Ralf]] 09:47, 20 May 2009 (UTC)
:No problem. Glad you are doing it:)--[[User:Gary Anderson|Gary Anderson]] 12:56, 20 May 2009 (UTC)

Modules and plugins improvements

2009-04-27T22:43:24Z

Ganderson: Added link and instructions to the page comments

The Modules and Plugins database provides a convenient way for Moodle System Administrators to search for available plugins, patches, and tools to enhance their installation. While the basic structure has been reasonably helpful, there is much to be desired in order to help those administrators determine things like the quality of the code, the reliability of the code, and the popularity of the code. This page is to help identify the areas needed for improvement and provide an path for implementing those improvements.

For example, I would like for there to be various levels of code. The first level would be verifying that the code has been independently tested by a Moodle developer, Moodle Partner or PHM to verify that the program at least appears to do what it says by someone of some repute. To say that the code is verified means that the code essentially works without any obvious bugs, PHP warning/notices, etc.

A similar indicator would be to have the code be "Moodle certified" which would mean that a Moodle developer or Moodle Partner has not only verified the functionality of the code but also the quality of the code. Certification would mean that the code conforms to Moodle's coding guidelines. Those wishing to have their code certified, could contact a Moodle Partner similar to how we handle the MCT. Code certified by a Moodle Partner indicates that the code is production ready and that the Moodle Partner would be comfortable having that code running on its servers.

Perhaps we could also develop a Moodle Certified Developer (MCD) which would mean that they have completed the Moodle Developer Course under the tutelage of a Moodle Partner and demonstrated the ability to code well according to Moodle coding guidelines.

The final code status indicator would be to say that it is hardened or secured. Secured code has been verified, certified, and also given a review by a security specialist (most likely Petr) to ensure that the code is unlikely to have any known security vulnerabilities. Here, I envision a Moodle Partner requesting that Petr review the code.

In addition to the code status indicator which serves as a type of quality assurance, it would be good to have popularity ratings. These should incorporate not only the number of downloads (from http://download.moodle.org/stats.php) but also the ratings that users give them. I would like to see some type of algorithm that would adjust the popularity based not merely on the average rating but also on the number of ratings such that the more popular plugins would outrank the less popular but highly rated ones.

Personally, I would like to receive an email with information about any new M&P entries. I would like to be able to filter the entries by various criteria and be able to do things like send a bulk message to all of those whose code is not on the Moodle CVS server (i.e. the download link does not contain http://download.moodle.org/download.php). As an aside, I am trying to ensure that I start adding the M&P entry URL to the component description to facilitate moving between places.

Please continue to add ideas, hopes, etc. as to how the Modules and Plugins database can become a more useful tool not only for those who maintain it but also for those who make use of it, either here or in the [[Development_talk:Modules_and_plugins_improvements | page comments]]

Part of what makes a plugin reputable is how quickly issues are responded to. I would want to be able to assess someone how actively the code is being maintained. We have a number of possible pieces of data but I do not know how we could calculate things in a meaningful way. The average time difference between when an issue is created and resolved might be helpful. Good code will not have many issues and thus not much activity; however, high activity indicates that it is actively being worked on. The last touch might be a semi-useful piece of information. Any other ideas?

Talk:Modules and plugins improvements

2009-04-26T17:33:19Z

Ganderson: Comments by Gary Anderon on module certification process

Anthony: I agree that this would be very helpful. Three suggestions:
* We should look at how other GNU web applications which have high rates of community contributions work, for example Drupal, MediaWiki, and WordPress. Perhaps a page (or section) of "Lesson's learned" from these projects would be useful for this discussion.
* I think it would be a good idea to expand the list of possible reviewers so that it does not focus too much only only the employees of Moodle.com (and I suspect that most of them would agree as well). Perhaps a way to do this is to have greater weight be given to those who have either contributed already certified code (that could include partners,HQ staff, or other contributors), or who have given effective reviews of a number of other modules, etc. To not discourage new-comers in the process, perhaps an review may need three net positive votes, where a new-comer can give one vote, but a pre-certified individual could give two or three votes, etc.
* Obviously, we need to keep it simple and not make the certification process too difficult. One way to do that may be to have a Wiki page on each contribution, and people could use the page comments to offer their reviews. Those wanting their contribution to be certified could solicit review. Before certification was given, they would need a certain amount of positive feedback, and all concerns raised in the feedback would need to be addressed (either with a fix or with a discussion that attempted to reach a consensus on any issues raised).--[[User:Gary Anderson|Gary Anderson]] 17:33, 26 April 2009 (UTC)

User:Gary Anderson

2009-03-29T03:39:23Z

Ganderson: Moved subpage links to bottom of page, other rearrangements

User talk:Gary Anderson

2009-03-29T03:34:48Z

Ganderson: Removed text that is on user page.

User:Gary Anderson

2009-03-22T18:26:33Z

Ganderson: Copied links from comments

I will use subpages of my talk area to make more detailed observations and analysis of current Moodle issues that may not work well in the tracker, the forums, or other areas of Moodle's documentation.

# [[User_talk:Gary_Anderson/Extra credit status | Extra credit status]]
# [[User_talk:Gary_Anderson/Examples of Extra Credit grading | Examples of Extra Credit grading]]
----
[[Image:GaryAndersonLava.jpg]]

Gary Anderson is a native of Seattle, a graduate of the University of Washington with degrees in Math, Business Economics, and certification in history education. He has a Master's degree in Teaching from Seattle University. Before entering teaching in 1996, he was the General Manager of the largest computer store in the Pacific Northwest which sold a majority of Apple II and Macintosh computers to schools, businesses and individuals around the I-5 corridor. He was also president of a software company that specialized in network communications.

Teaching is the family business for Gary. Both of his parents are retired teachers, and his brother is the principal of a middle school and his sister is an elementary school teacher.

His research interest is in the technology of instruction, and in particular the effects on student achievement when they receive rapid feedback on their performance. He has designed a number of software projects in advancement of this effort. He is currently working on a Moodle activity based on the theory of [http://en.wikipedia.org/wiki/Spaced_repetition Spaced Repetition] and another activity that customizes Wikimedia software for use in secondary school education.

Gary is the head of the Math Department at Seattle Academy and wonderful private, college prep, independent school that among many other things is in the 12th year of a universal laptop program for it's upper school. He teaches Advance Algebra, Second Year Calculus, and elective trimesters in Statistics, Math Modeling and Software Development. These math electives are the most popular electives in the school.

For the past 4 years, Gary has been known as the Moodle Master and has customized the software to make it especially usable in the high school environment (see [[Seattle_Academy]]). He is now turning over this day-to-day responsibility to has technology department and Curriculum Technology Coordinator Vicki Butler so the he can focus on being more involved in the larger technology community, contributing what he has learned from overseeing the school's Moodle project and other educational technology initiatives.

[[Image:GaryAndersonMoodleMaster.jpg]]

User:Gary Anderson/Extra credit status

2009-03-22T18:25:04Z

Ganderson: Copied text to actual page rather than comment page

Since the discussion of extra credit appears in several tracker and forum issues, I will keep this personal subpage up-to-date on the current status rather than making a bunch of individual postings. Feel free to use the page comments tab if you have something constructive to say about this page. --[[User:Gary Anderson|Gary Anderson]] 19:05, 21 March 2009 (UTC)

Response to [[http://tracker.moodle.org/browse/MDL-12942?focusedCommentId=67172&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#action_67172 | MDL-12942]]

Petr:

I added to the article http://en.wikipedia.org/w/index.php?title=Extra_credit to give reasons for use and methods of computation. Does that resolve the issue:)?

To consolidate my views on this at this overall issue at this point in time:

1. I think a global switch in $CFG is the best compromise to the over 100% on a given activity. The instructions for use will be use in a tutorial that I will write into docs on how to do this type of extra credit. For institutions where this is desired, it should be an acceptable approach (as opposed to needing it to be an admin block switch).

2. I think recalculating grades on changing this setting is unneeded and dangerous. I base this both on my own tests of my latest patch in MDL-12380, the use of a fixed patch at my school for more than 4 trimesters, and the experience reported of the LSU gradebook. I recognize that recalculation might happen at later times, but a one time disabling of this feature would cause all data to be lost of grades that exceed 100%.

3. Which brings me to my concern about the existing strategy of rounding to the boundary. If one accepts the premise that grades can never exceed a maximum value, then the software should reject such a condition and not write to the database -- it should give some type of warning or exception instead. This is most likely a data entry error or data corruption error and setting it to some bounded value corrupts the data further.

4. My objection to adding new aggregation types is in the adding of complexity to an already difficult gradeboook. I don't mind using those values in the database in the grade_items table, it is just that it should be set or not by a checkbox in the Category and items form, and not by making the user select a different aggregation type. I am also not sure if that method would allow individual items to be extra credit which is really what is needed. A better solution would be to add a column to the grade_items table, but that would require changing the scheme within a version.

5. We do have this second type of extra credit (optional activities) working at our school, but I hacked it by having the title of the activity appended with a **. This allows an item to be made extra credit without having to go into the gradebook. Still, we have worked out the computation issues, which just basically increases the numerator but not the denominator.

6. As for the international acceptance issue, it does seem that some of these features have a US focus (as does the letter grade scales). But I suspect that other teachers throughout the world give optional work, and at least in some cases, have a way for accounting for that in a student's assessment.

7. A selfish part of me is wishing that this issue is not addressed because I already have it fixed for myself and my colleagues. Any fixes in core will mean I have to go back and undo these things that are working. But ultimately I don't think the feature request will go away unless addressed. So, when the issue comes up in the community, I jump back in.

I do appreciate all your hard work for Moodle which I think is a great even if imperfect tool that can really improve educational possibilities throughout the world. I find it invaluable in my own classroom. It is just that my experience as a teacher does not match with your sensibilities as a programmer sometimes, although I remain hopeful that this process may still lead to a more successful product for teachers and students everywhere.

Take care,

--Gary

User talk:Gary Anderson/Extra credit status

2009-03-21T19:05:51Z

Ganderson: Response to MDL-12942

User talk:Gary Anderson

2009-03-21T18:53:39Z

Ganderson:

See [[User:Gary_Anderson]] for a detailed description of my background.

----

I will use subpages of my talk area to make more detailed observations and analysis of current Moodle issues that may not work well in the tracker, the forums, or other areas of Moodle's documentation.

# [[User_talk:Gary_Anderson/Extra credit status | Extra credit status]]
# [[User_talk:Gary_Anderson/Examples of Extra Credit grading | Examples of Extra Credit grading]]

User talk:Gary Anderson/Examples of Extra Credit grading

2009-03-09T02:49:16Z

Ganderson: Extra credit grading strategies described

'''''by Gary Anderson'''''

''(Please add any comments using the page comments tab rather than editing this page)''

The following are examples of course grading descriptions that use Extra Credit. Each strategy should be possible within Moodle in a way that is intuitive to teachers without special training, and the computations should be natural and obvious. Ideally they simply enter the extra points to an existing activity or to a special extra credit activity.

Note that I don't always use Extra Credit in my classes, but when I do, it has these characteristics.

* Software Development: Spring 2009. Teacher: Gary Anderson

Grading: Grading in this course is very simple. One Friday of each week you will write a reflection in Moodle on the work you have done, the successes and challenges you have had, and your plan for moving forward. This assignment is worth 10 points each week. In addition, you may earn a small number of extra credit points by doing work that clearly goes beyond the requirements of the course and is in addition to all assigned tasks. Make sure you clearly document and justify this additional effort to qualify for extra credit.

* Advanced Algebra: Spring 2009. Teacher: Gary Anderson

Grading: 60% of your term grade is for daily work which including regular homework assignments, projects, participation, and other activities. 40% of your grade is for quizzes and tests. You may earn an additional 10 Extra-Credit points each week which will be added to your daily work category by doing the "Problems of the Week" found on saasmath.com. Occasionally, an optional and more challenging extra-credit problem will also be added to a quiz or test.

* Advanced Algebra: Spring 2009. Teacher: Gary Anderson

Grading: 60% of your term grade is for quizzes, tests, and exams. 40% of your grade is for daily work. In addition, you may earn up to 5% extra credit by doing the optional problems found at saasmath.com.

User talk:Gary Anderson

2009-03-09T02:02:13Z

Ganderson: Start of personal essays on Moodle

See [[User:Gary_Anderson]] for a detailed description of my background.

----

I will use subpages of my talk area to make more detailed observations and analysis of current Moodle issues that may not work well in the tracker, the forums, or other areas of Moodle's documentation.

# [[User_talk:Gary_Anderson/The uses of Extra Credit | The benefit of Extra Credit]]
# [[User_talk:Gary_Anderson/Examples of Extra Credit grading | Examples of Extra Credit grading]]

User:Gary Anderson

2009-03-09T01:53:08Z

Ganderson: Update to status

[[Image:GaryAndersonLava.jpg]]

Gary Anderson is a native of Seattle, a graduate of the University of Washington with degrees in Math, Business Economics, and certification in history education. He has a Master's degree in Teaching from Seattle University. Before entering teaching in 1996, he was the General Manager of the largest computer store in the Pacific Northwest which sold a majority of Apple II and Macintosh computers to schools, businesses and individuals around the I-5 corridor. He was also president of a software company that specialized in network communications.

Teaching is the family business for Gary. Both of his parents are retired teachers, and his brother is the principal of a middle school and his sister is an elementary school teacher.

His research interest is in the technology of instruction, and in particular the effects on student achievement when they receive rapid feedback on their performance. He has designed a number of software projects in advancement of this effort. He is currently working on a Moodle activity based on the theory of [http://en.wikipedia.org/wiki/Spaced_repetition Spaced Repetition] and another activity that customizes Wikimedia software for use in secondary school education.

Gary is the head of the Math Department at Seattle Academy and wonderful private, college prep, independent school that among many other things is in the 12th year of a universal laptop program for it's upper school. He teaches Advance Algebra, Second Year Calculus, and elective trimesters in Statistics, Math Modeling and Software Development. These math electives are the most popular electives in the school.

For the past 4 years, Gary has been known as the Moodle Master and has customized the software to make it especially usable in the high school environment (see [[Seattle_Academy]]). He is now turning over this day-to-day responsibility to has technology department and Curriculum Technology Coordinator Vicki Butler so the he can focus on being more involved in the larger technology community, contributing what he has learned from overseeing the school's Moodle project and other educational technology initiatives.

[[Image:GaryAndersonMoodleMaster.jpg]]

User talk:Gary Anderson

2009-03-09T01:29:51Z

Ganderson: Personal page start

Gary Anderson has been involved in educational technology for most of his professional life, first as the general manager of a large computer store in the Pacific Northwest of the United States, then as a software developer, and for the past dozen years he has joined the rest of his family in a career as a teacher.

His research interest is investigating ways that students, when given quick feedback, can improve the effectiveness of learning.

He is the Math Department Chair of Seattle Academy, a private college-prep school, where he teaches second-year Calculus, Advanced Algebra, and a sequence of math electives including statistics, math modeling, and software development.

He has extensively customized Moodle for the classroom environment with a couple dozen sets of patches (see [[Seattle_Academy]]), a handful of blocks, and 2 activity modules including one based on the theory of spaced repetition. He is now also customizing Mediawiki to work well in the high school environment.

Usability testing protocol

2008-09-21T20:55:10Z

Ganderson: Helpful references

This page is in early development.

This page describes the recommended end-user testing that new features should undergo before being added to Moodle. The process is intended identify difficulties or confusion that targeted users might encounter and communicate that information during appropriate parts of the development cycle for the purpose of improving the end-user experience.

=Testing Phases=

==Developer questionnaire==
This will include items such:

* who the targeted user is (Site administrator, power-user teacher, standard teacher, student, etc.)
* what end-user testing has the developer already undertaken, if any (and what was learned from this)
* what level of instruction or training is anticipated to use the feature, or whether the developer feels the feature's use is self-evident and intuitive
* what other interface is this feature similar to or was inspired by (either within Moodle or with another application)
* whether all features are included in the current form for the next anticipated release of the feature

==Task list devised==
Tasks the developer wants the end user to try to perform should be listed. There should also be the opportunity for additional tasks to be added by the end-user based on his or her perception of how the feature will be used.

In some cases it may be best to use actual data in performing a task when appropriate to find issues that will happen in practice. Coordination should be made with the subject being tested to make sure the environment and data are similar to what will be used in practice.

==End-user test subjects identified==

It should be recognized that there are diminishing returns to adding more testers in most cases. The most significant results will be found with observations made by the first subject who is a typical end-user. Still, when possible, users in different environments such as schools, distant learning courses, trainers, professors of large university classes, users with limited technical skills, etc. can add additional perspective and should be included if their use may be significantly different.

==Testing transcript==

Ideally the end user will be observed as she/he attempts to perform the items on the task list and notes should be taken of the process and difficulties. The observer should try not to give assistance during the process, but when help is needed, notice should be made of what assistance was required.

When an observer is not available, the end-user should describe the experience and steps and difficulties encountered in the testing process.

==Summary and suggestions==

Based on what happens during testing, a summary and set of recommendations should be constructed to be communicated to the developer. It should include a recommendation as to what degree additional refinement and retesting is needed. These reports need not be lengthy. If a feature is well designed few if any recommendations are needed. If it has many usability issues, that should be communicated with a few areas to be addressed first.

==Collation==

If multiple institutions did testing, a coordinator should collate the findings and give a quick summary of what were common themes and differences and give a summary recommendation.

==Refinement and retesting==

Based on the feedback received, the developer should make decisions on refining the feature to improve usability. He or she should make some sort of response to the feedback and if changes made are significant the feature should be resubmitted for going through the retesting protocol.

=Helpful references=

==Web resources==

* http://en.wikipedia.org/wiki/Usability_testing

* http://fluidproject.org/

* http://www.usability.gov/

* http://www.utexas.edu/learn/usability/

==Conferences==

* http://www.uie.com/events/uiconf/2008/

==Journals==

* http://www.upassoc.org/upa_publications/jus/jus_home.html

==Books==

* Don't Make Me Think: A Common Sense Approach to Web Usability ISBN 0321344758

* Designing Interfaces: Patterns for Effective Interaction Design ISBN 0596008031

* Handbook of Usability Testing: ISBN 0470185481

* Moderating Usability Tests: ISBN 0123739330

* Measuring the User Experience: ISBN 0123735580

Usability testing protocol

2008-09-21T14:20:20Z

Ganderson: /* Helpful references */

This page is in early development.

This page describes the recommended end-user testing that new features should undergo before being added to Moodle. The process is intended identify difficulties or confusion that targeted users might encounter and communicate that information during appropriate parts of the development cycle for the purpose of improving the end-user experience.

=Testing Phases=

==Developer questionnaire==
This will include items such:

* who the targeted user is (Site administrator, power-user teacher, standard teacher, student, etc.)
* what end-user testing has the developer already undertaken, if any (and what was learned from this)
* what level of instruction or training is anticipated to use the feature, or whether the developer feels the feature's use is self-evident and intuitive
* what other interface is this feature similar to or was inspired by (either within Moodle or with another application)
* whether all features are included in the current form for the next anticipated release of the feature

==Task list devised==
Tasks the developer wants the end user to try to perform should be listed. There should also be the opportunity for additional tasks to be added by the end-user based on his or her perception of how the feature will be used.

In some cases it may be best to use actual data in performing a task when appropriate to find issues that will happen in practice. Coordination should be made with the subject being tested to make sure the environment and data are similar to what will be used in practice.

==End-user test subjects identified==

It should be recognized that there are diminishing returns to adding more testers in most cases. The most significant results will be found with observations made by the first subject who is a typical end-user. Still, when possible, users in different environments such as schools, distant learning courses, trainers, professors of large university classes, users with limited technical skills, etc. can add additional perspective and should be included if their use may be significantly different.

==Testing transcript==

Ideally the end user will be observed as she/he attempts to perform the items on the task list and notes should be taken of the process and difficulties. The observer should try not to give assistance during the process, but when help is needed, notice should be made of what assistance was required.

When an observer is not available, the end-user should describe the experience and steps and difficulties encountered in the testing process.

==Summary and suggestions==

Based on what happens during testing, a summary and set of recommendations should be constructed to be communicated to the developer. It should include a recommendation as to what degree additional refinement and retesting is needed. These reports need not be lengthy. If a feature is well designed few if any recommendations are needed. If it has many usability issues, that should be communicated with a few areas to be addressed first.

==Collation==

If multiple institutions did testing, a coordinator should collate the findings and give a quick summary of what were common themes and differences and give a summary recommendation.

==Refinement and retesting==

Based on the feedback received, the developer should make decisions on refining the feature to improve usability. He or she should make some sort of response to the feedback and if changes made are significant the feature should be resubmitted for going through the retesting protocol.

=Helpful references=

* http://en.wikipedia.org/wiki/Usability_testing

* http://fluidproject.org/

* http://www.usability.gov/

* http://www.utexas.edu/learn/usability/

* http://www.uie.com/events/uiconf/2008/

* Don't Make Me Think: A Common Sense Approach to Web Usability ISBN 0321344758

* Designing Interfaces: Patterns for Effective Interaction Design ISBN 0596008031

* Handbook of Usability Testing: ISBN 0470185481

* Moderating Usability Tests: ISBN 0123739330

* Measuring the User Experience: ISBN 0123735580

Usability testing protocol

2008-09-21T09:06:40Z

Ganderson: /* Helpful references */

This page is in early development.

This page describes the recommended end-user testing that new features should undergo before being added to Moodle. The process is intended identify difficulties or confusion that targeted users might encounter and communicate that information during appropriate parts of the development cycle for the purpose of improving the end-user experience.

=Testing Phases=

==Developer questionnaire==
This will include items such:

* who the targeted user is (Site administrator, power-user teacher, standard teacher, student, etc.)
* what end-user testing has the developer already undertaken, if any (and what was learned from this)
* what level of instruction or training is anticipated to use the feature, or whether the developer feels the feature's use is self-evident and intuitive
* what other interface is this feature similar to or was inspired by (either within Moodle or with another application)
* whether all features are included in the current form for the next anticipated release of the feature

==Task list devised==
Tasks the developer wants the end user to try to perform should be listed. There should also be the opportunity for additional tasks to be added by the end-user based on his or her perception of how the feature will be used.

In some cases it may be best to use actual data in performing a task when appropriate to find issues that will happen in practice. Coordination should be made with the subject being tested to make sure the environment and data are similar to what will be used in practice.

==End-user test subjects identified==

It should be recognized that there are diminishing returns to adding more testers in most cases. The most significant results will be found with observations made by the first subject who is a typical end-user. Still, when possible, users in different environments such as schools, distant learning courses, trainers, professors of large university classes, users with limited technical skills, etc. can add additional perspective and should be included if their use may be significantly different.

==Testing transcript==

Ideally the end user will be observed as she/he attempts to perform the items on the task list and notes should be taken of the process and difficulties. The observer should try not to give assistance during the process, but when help is needed, notice should be made of what assistance was required.

When an observer is not available, the end-user should describe the experience and steps and difficulties encountered in the testing process.

==Summary and suggestions==

Based on what happens during testing, a summary and set of recommendations should be constructed to be communicated to the developer. It should include a recommendation as to what degree additional refinement and retesting is needed. These reports need not be lengthy. If a feature is well designed few if any recommendations are needed. If it has many usability issues, that should be communicated with a few areas to be addressed first.

==Collation==

If multiple institutions did testing, a coordinator should collate the findings and give a quick summary of what were common themes and differences and give a summary recommendation.

==Refinement and retesting==

Based on the feedback received, the developer should make decisions on refining the feature to improve usability. He or she should make some sort of response to the feedback and if changes made are significant the feature should be resubmitted for going through the retesting protocol.

=Helpful references=

* http://en.wikipedia.org/wiki/Usability_testing

* http://fluidproject.org/

* http://www.usability.gov/

* Don't Make Me Think: A Common Sense Approach to Web Usability ISBN 0321344758

* Designing Interfaces: Patterns for Effective Interaction Design ISBN 0596008031

* Handbook of Usability Testing: ISBN 0470185481

* Moderating Usability Tests: ISBN 0123739330

* Measuring the User Experience: ISBN 0123735580

Usability testing protocol

2008-09-20T16:09:06Z

Ganderson: Helpful references list started

This page is in early development.

This page describes the recommended end-user testing that new features should undergo before being added to Moodle. The process is intended identify difficulties or confusion that targeted users might encounter and communicate that information during appropriate parts of the development cycle for the purpose of improving the end-user experience.

=Testing Phases=

==Developer questionnaire==
This will include items such:

* who the targeted user is (Site administrator, power-user teacher, standard teacher, student, etc.)
* what end-user testing has the developer already undertaken, if any (and what was learned from this)
* what level of instruction or training is anticipated to use the feature, or whether the developer feels the feature's use is self-evident and intuitive
* what other interface is this feature similar to or was inspired by (either within Moodle or with another application)
* whether all features are included in the current form for the next anticipated release of the feature

==Task list devised==
Tasks the developer wants the end user to try to perform should be listed. There should also be the opportunity for additional tasks to be added by the end-user based on his or her perception of how the feature will be used.

In some cases it may be best to use actual data in performing a task when appropriate to find issues that will happen in practice. Coordination should be made with the subject being tested to make sure the environment and data are similar to what will be used in practice.

==End-user test subjects identified==

It should be recognized that there are diminishing returns to adding more testers in most cases. The most significant results will be found with observations made by the first subject who is a typical end-user. Still, when possible, users in different environments such as schools, distant learning courses, trainers, professors of large university classes, users with limited technical skills, etc. can add additional perspective and should be included if their use may be significantly different.

==Testing transcript==

Ideally the end user will be observed as she/he attempts to perform the items on the task list and notes should be taken of the process and difficulties. The observer should try not to give assistance during the process, but when help is needed, notice should be made of what assistance was required.

When an observer is not available, the end-user should describe the experience and steps and difficulties encountered in the testing process.

==Summary and suggestions==

Based on what happens during testing, a summary and set of recommendations should be constructed to be communicated to the developer. It should include a recommendation as to what degree additional refinement and retesting is needed. These reports need not be lengthy. If a feature is well designed few if any recommendations are needed. If it has many usability issues, that should be communicated with a few areas to be addressed first.

==Collation==

If multiple institutions did testing, a coordinator should collate the findings and give a quick summary of what were common themes and differences and give a summary recommendation.

==Refinement and retesting==

Based on the feedback received, the developer should make decisions on refining the feature to improve usability. He or she should make some sort of response to the feedback and if changes made are significant the feature should be resubmitted for going through the retesting protocol.

=Helpful references=

* http://en.wikipedia.org/wiki/Usability_testing

* http://fluidproject.org/

* http://www.usability.gov/

* Don't Make Me Think: A Common Sense Approach to Web Usability ISBN 0321344758

* Designing Interfaces: Patterns for Effective Interaction Design ISBN 0596008031

Usability testing protocol

2008-09-19T14:02:16Z

Ganderson: Minor edits

Usability testing protocol

2008-09-19T10:52:43Z

Ganderson: /* Refinement and retesting */

This page is in early development.

This page describes the recommended end-user testing that new features should undergo before being added to Moodle. The process is intended identify difficulties or confusion that targeted users might encounter and communicate that information during appropriate parts of the development cycle for the purposes of improving the end-user experience.

=Testing Phases=

==Developer questionnaire==
This will include items such:

* who the targeted user is (Site administrator, power-user teacher, standard teacher, student, etc.).
* what end-user testing has the developer already undertaken, if any (and what was learned from this)
* what level of instruction or training is anticipated to use the feature, or whether the developer feels the features use is self-evident and intuitive
* what other interface is this feature similar to or was inspired by (either within Moodle or with another application)
* whether all features are included in the current form for the next anticipated release of the feature

==Task list devised==
Tasks the developer wants the end user to try to perform. There should also be the opportunity for additional tasks to be added by the end-user based on his or her perception of how the feature will be used.

In some cases it may be best to use actual data in performing a task when appropriate to find issues that will happen in practice.

==End-user test subjects identified==

It should be recognized that there are diminishing returns to adding more testers in most cases. The most significant results will be found with observations made by the first subject who is a typical end-user. Still, when possible, users in different environments such as schools, distant learning courses, trainers, professors of large university classes, users with limited technical skills, etc. can add additional perspective.

==Testing transcript==

Ideally the end user will be observed as she/he attempts to perform the tasks on the task list and notes should be taken of the process and difficulties. The observer should try not to give assistance during the process, but when it is needed, notice should be made of what assistance is needed.

When an observer is not available, the end-user should describe the experience and steps and difficulties encountered in the testing process.

==Summary and suggestions==

Based on what happens during testing, a summary and set of recommendations should be constructed to be communicated to the developer. It should include a recommendation of to what degree additional refinement and retesting is needed. These reports need not be lengthy. If a feature is well designed few if any recommendations are needed. If it has many usability issues, that should be communicated with a few areas to be addressed first.

==Collation==

If multiple institutions did testing, a coordinator should collate the findings and give a quick summary of what were common themes and differences and give a summary recommendation.

==Refinement and retesting==

Based on the feedback received, the developer should make decisions on refining the feature to improve usability. He or she should make some sort of response to the feedback and if changes made are significant the feature should be resubmitted for going through the retesting protocol.

Usability testing protocol

2008-09-19T10:48:09Z

Ganderson: Testing phases

This page is in early development.

This page describes the recommended end-user testing that new features should undergo before being added to Moodle. The process is intended identify difficulties or confusion that targeted users might encounter and communicate that information during appropriate parts of the development cycle for the purposes of improving the end-user experience.

=Testing Phases=

==Developer questionnaire==
This will include items such:

* who the targeted user is (Site administrator, power-user teacher, standard teacher, student, etc.).
* what end-user testing has the developer already undertaken, if any (and what was learned from this)
* what level of instruction or training is anticipated to use the feature, or whether the developer feels the features use is self-evident and intuitive
* what other interface is this feature similar to or was inspired by (either within Moodle or with another application)
* whether all features are included in the current form for the next anticipated release of the feature

==Task list devised==
Tasks the developer wants the end user to try to perform. There should also be the opportunity for additional tasks to be added by the end-user based on his or her perception of how the feature will be used.

In some cases it may be best to use actual data in performing a task when appropriate to find issues that will happen in practice.

==End-user test subjects identified==

It should be recognized that there are diminishing returns to adding more testers in most cases. The most significant results will be found with observations made by the first subject who is a typical end-user. Still, when possible, users in different environments such as schools, distant learning courses, trainers, professors of large university classes, users with limited technical skills, etc. can add additional perspective.

==Testing transcript==

Ideally the end user will be observed as she/he attempts to perform the tasks on the task list and notes should be taken of the process and difficulties. The observer should try not to give assistance during the process, but when it is needed, notice should be made of what assistance is needed.

When an observer is not available, the end-user should describe the experience and steps and difficulties encountered in the testing process.

==Summary and suggestions==

Based on what happens during testing, a summary and set of recommendations should be constructed to be communicated to the developer. It should include a recommendation of to what degree additional refinement and retesting is needed. These reports need not be lengthy. If a feature is well designed few if any recommendations are needed. If it has many usability issues, that should be communicated with a few areas to be addressed first.

==Collation==

If multiple institutions did testing, a coordinator should collate the findings and give a quick summary of what were common themes and differences and give a summary recommendation.

==Refinement and retesting==

Based on the feedback received, the developer should make decisions on refining the feature to improve usability. He or she should make some sort of response to the feedback and if changes made are significant.

Usability testing protocol

2008-09-19T10:00:06Z

Ganderson: Start of page

Patching forms tutorial

2008-06-18T18:51:10Z

Ganderson: /* Changing the default course start date and duration */

by Gary Anderson

One of the easiest local modifications that an institution can make to customize their Moodle site is to make simple changes to the form elements that appear on pages. This permits one to set different default values when creating new items, allows one to hide unused input elements to simplify the interface, and lets one identify certain more complicated elements as "advanced" so that features are still availale while simplifying the interface for most uses.

This tutorial will demonstrate how to do such modifications.

'''Warning'''
Making custom changes to the PHP scripting code in Moodle should be done carefully.
You should always test your code before using it on your production site and should backup the original scripts.
You should always comment your code so you know what has been changed.
Care should also be taken during upgrades in the code to make sure things are not broken (like conflicts during a CVS update).

Having said that, these patches are among the simplest and the recovery from an error is easy: simply replace the file with original from the core distribution.

'''Moodle Forms Overview'''

Rather than placing HTML form elements directly on the page, most well-written Moodle code will use the Forms Library. This allows a standard way to create user input elements and also centralizes code making it easier to override certain behaviors creating a greater consistency.

An entire form is an "object" with methods and attributes. In many places in the Moodle code, the instance of the object is identified my the variable $mform, but you can use any variable.

Common methods of the form object look like:

* $mform->addelement(<elementtype>,<elementidentifier>,<displayname>,<options>);

This creates a new input element on a page.

While forms can be produced in any scripting page which outputs code, you will often find code for printing out forms in a file like mod_form.php or in index.php of the affected component. The examine the URL of the page being viewed as a starting point for finding the file to be changed.

Always comment your code so you can change or remove it later.. For single line modifications, considering putting in your new code, and then and it with //<yourusername> <date> <the old code>. This allows for retention of eisting line numbers.

==Changing defaults==

The '''setDefault''' method is used to establish the initial value used in the form and allows you to to define the most common setting for use in your institution.

Example: Change the default number of points for a default assignment from 100 points to 10 points.

Solution:

In the file /mod/assignment/mod_form.php, find

$mform->setDefault('grade', 100);

Change the default to 10, and comment out the previous code with your initial and dates:

$mform->setDefault('grade', 10); //GVA 20080608 $mform->setDefault('grade', 100);

==Hiding fields==

Form elements are created for a page using the '''addElement''' method. Various types of element are text, select, date_time_selector, htmleditor, etc.

There is also the type "hidden" that defines the element on a page and allows you to set a default value, stores previous values from a submission etc. To simplify your forms for you users, simply change the type of the field during when addElement is called to hidden.

Example: Your site does not want to use meta courses and you want to remove it from the course creation/edit page. In the file /course/edit_form.php

Change:

$mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

to

$mform->addElement('hidden', 'metacourse', get_string('managemeta'), $meta); //GVA 20080610 $mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

==Setting fields to "Advanced"==

For elements that are infrequently used in your institution, you can still simplify the interface while making options still available to your 'Power Users' by marking elements as "advanced".

These elements only appear to the user when the click the "Set Advanced" button.

To identify the element as advanced, call the '''setAdvanced''' method after the element has been created.

Example:

Your typical user is local and hence it will be rare that they will use a different time zone. To clean up the interface, set the option to change the user time zone so that it is shown only when the user clicks "Set Advanced".

Solution:

In the file /user/editlib.php, find:

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);

Set the field to advanced using the setAdvanced method

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);
$mform->setAdvanced('timezone');

==Other Examples==
Here are some other example of making simple changes to forms
===Change the maximum allowed grade===
The maximum grade for a module is set in the standard form to 100. To change this to a different value (such as 200) in version 1.9, make this change in the file '''/lib/form/modgrade.php'''

Find:

for ($i=100; $i>=1; $i--) {

Change to:

for ($i=200; $i>=1; $i--) { // GVA 20080616 for ($i=100; $i>=1; $i--) {

===Set a standard start date and number of weeks for courses===

By default, Moodle starts courses on the day following course creation and gives them a duration of 10 weeks. As many institutions have standard terms, setting the default start date and duration will allow for more uniformity, fewer mistakes, and will ease course creation.

In version 1.9, edit the file '''/course/edit_form.php'''. Insert the following lines after the affected fields are defined (perhaps on lines just before $this->add_action_buttons();)

//GVA 20080618 Number of weeks for default course. Should go through final exam
$mform->setDefault('numsections', 13);
//GVA 20080618 Set default course start date. Always start on a Monday to have weeks work right
$mform->setDefault('startdate', strtotime("1 Sep 2008"));

Patching forms tutorial

2008-06-16T21:34:38Z

Ganderson: /* Change the maximum allowed grade to, for example, 200*/

by Gary Anderson

One of the easiest local modifications that an institution can make to customize their Moodle site is to make simple changes to the form elements that appear on pages. This permits one to set different default values when creating new items, allows one to hide unused input elements to simplify the interface, and lets one identify certain more complicated elements as "advanced" so that features are still availale while simplifying the interface for most uses.

This tutorial will demonstrate how to do such modifications.

'''Warning'''
Making custom changes to the PHP scripting code in Moodle should be done carefully.
You should always test your code before using it on your production site and should backup the original scripts.
You should always comment your code so you know what has been changed.
Care should also be taken during upgrades in the code to make sure things are not broken (like conflicts during a CVS update).

Having said that, these patches are among the simplest and the recovery from an error is easy: simply replace the file with original from the core distribution.

'''Moodle Forms Overview'''

Rather than placing HTML form elements directly on the page, most well-written Moodle code will use the Forms Library. This allows a standard way to create user input elements and also centralizes code making it easier to override certain behaviors creating a greater consistency.

An entire form is an "object" with methods and attributes. In many places in the Moodle code, the instance of the object is identified my the variable $mform, but you can use any variable.

Common methods of the form object look like:

* $mform->addelement(<elementtype>,<elementidentifier>,<displayname>,<options>);

This creates a new input element on a page.

While forms can be produced in any scripting page which outputs code, you will often find code for printing out forms in a file like mod_form.php or in index.php of the affected component. The examine the URL of the page being viewed as a starting point for finding the file to be changed.

Always comment your code so you can change or remove it later.. For single line modifications, considering putting in your new code, and then and it with //<yourusername> <date> <the old code>. This allows for retention of eisting line numbers.

==Changing defaults==

The '''setDefault''' method is used to establish the initial value used in the form and allows you to to define the most common setting for use in your institution.

Example: Change the default number of points for a default assignment from 100 points to 10 points.

Solution:

In the file /mod/assignment/mod_form.php, find

$mform->setDefault('grade', 100);

Change the default to 10, and comment out the previous code with your initial and dates:

$mform->setDefault('grade', 10); //GVA 20080608 $mform->setDefault('grade', 100);

==Hiding fields==

Form elements are created for a page using the '''addElement''' method. Various types of element are text, select, date_time_selector, htmleditor, etc.

There is also the type "hidden" that defines the element on a page and allows you to set a default value, stores previous values from a submission etc. To simplify your forms for you users, simply change the type of the field during when addElement is called to hidden.

Example: Your site does not want to use meta courses and you want to remove it from the course creation/edit page. In the file /course/edit_form.php

Change:

$mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

to

$mform->addElement('hidden', 'metacourse', get_string('managemeta'), $meta); //GVA 20080610 $mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

==Setting fields to "Advanced"==

For elements that are infrequently used in your institution, you can still simplify the interface while making options still available to your 'Power Users' by marking elements as "advanced".

These elements only appear to the user when the click the "Set Advanced" button.

To identify the element as advanced, call the '''setAdvanced''' method after the element has been created.

Example:

Your typical user is local and hence it will be rare that they will use a different time zone. To clean up the interface, set the option to change the user time zone so that it is shown only when the user clicks "Set Advanced".

Solution:

In the file /user/editlib.php, find:

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);

Set the field to advanced using the setAdvanced method

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);
$mform->setAdvanced('timezone');

==Other Examples==
Here are some other example of making simple changes to forms
===Change the maximum allowed grade===
The maximum grade for a module is set in the standard form to 100. To change this to a different value (such as 200) in version 1.9, make this change in the file /lib/form/modgrade.php

Find:

for ($i=100; $i>=1; $i--) {

Change to:

for ($i=200; $i>=1; $i--) { // GVA 20080616 for ($i=100; $i>=1; $i--) {

Patching forms tutorial

2008-06-16T21:31:03Z

Ganderson: Change maximum grade

by Gary Anderson

One of the easiest local modifications that an institution can make to customize their Moodle site is to make simple changes to the form elements that appear on pages. This permits one to set different default values when creating new items, allows one to hide unused input elements to simplify the interface, and lets one identify certain more complicated elements as "advanced" so that features are still availale while simplifying the interface for most uses.

This tutorial will demonstrate how to do such modifications.

'''Warning'''
Making custom changes to the PHP scripting code in Moodle should be done carefully.
You should always test your code before using it on your production site and should backup the original scripts.
You should always comment your code so you know what has been changed.
Care should also be taken during upgrades in the code to make sure things are not broken (like conflicts during a CVS update).

Having said that, these patches are among the simplest and the recovery from an error is easy: simply replace the file with original from the core distribution.

'''Moodle Forms Overview'''

Rather than placing HTML form elements directly on the page, most well-written Moodle code will use the Forms Library. This allows a standard way to create user input elements and also centralizes code making it easier to override certain behaviors creating a greater consistency.

An entire form is an "object" with methods and attributes. In many places in the Moodle code, the instance of the object is identified my the variable $mform, but you can use any variable.

Common methods of the form object look like:

* $mform->addelement(<elementtype>,<elementidentifier>,<displayname>,<options>);

This creates a new input element on a page.

While forms can be produced in any scripting page which outputs code, you will often find code for printing out forms in a file like mod_form.php or in index.php of the affected component. The examine the URL of the page being viewed as a starting point for finding the file to be changed.

Always comment your code so you can change or remove it later.. For single line modifications, considering putting in your new code, and then and it with //<yourusername> <date> <the old code>. This allows for retention of eisting line numbers.

==Changing defaults==

The '''setDefault''' method is used to establish the initial value used in the form and allows you to to define the most common setting for use in your institution.

Example: Change the default number of points for a default assignment from 100 points to 10 points.

Solution:

In the file /mod/assignment/mod_form.php, find

$mform->setDefault('grade', 100);

Change the default to 10, and comment out the previous code with your initial and dates:

$mform->setDefault('grade', 10); //GVA 20080608 $mform->setDefault('grade', 100);

==Hiding fields==

Form elements are created for a page using the '''addElement''' method. Various types of element are text, select, date_time_selector, htmleditor, etc.

There is also the type "hidden" that defines the element on a page and allows you to set a default value, stores previous values from a submission etc. To simplify your forms for you users, simply change the type of the field during when addElement is called to hidden.

Example: Your site does not want to use meta courses and you want to remove it from the course creation/edit page. In the file /course/edit_form.php

Change:

$mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

to

$mform->addElement('hidden', 'metacourse', get_string('managemeta'), $meta); //GVA 20080610 $mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

==Setting fields to "Advanced"==

For elements that are infrequently used in your institution, you can still simplify the interface while making options still available to your 'Power Users' by marking elements as "advanced".

These elements only appear to the user when the click the "Set Advanced" button.

To identify the element as advanced, call the '''setAdvanced''' method after the element has been created.

Example:

Your typical user is local and hence it will be rare that they will use a different time zone. To clean up the interface, set the option to change the user time zone so that it is shown only when the user clicks "Set Advanced".

Solution:

In the file /user/editlib.php, find:

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);

Set the field to advanced using the setAdvanced method

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);
$mform->setAdvanced('timezone');

==Other Examples==
Here are some other example of making simple changes to forms
===Change the maximum allowed grade===
The maximum grade for a module is set in the standard form to 100. To change this to a different value, change it in the file /lib/form/modgrade.php

Find:

for ($i=100; $i>=1; $i--) {

Change to:

for ($i=100; $i>=1; $i--) { // GVA 20080616 for ($i=100; $i>=1; $i--) {

Patching forms tutorial

2008-06-10T09:06:20Z

Ganderson: /* Setting fields to "Advanced" */

by Gary Anderson

One of the easiest local modifications that an institution can make to customize their Moodle site is to make simple changes to the form elements that appear on pages. This permits one to set different default values when creating new items, allows one to hide unused input elements to simplify the interface, and lets one identify certain more complicated elements as "advanced" so that features are still availale while simplifying the interface for most uses.

This tutorial will demonstrate how to do such modifications.

===Warning===
Making custom changes to the PHP scripting code in Moodle should be done carefully. You should always test your code before using it on your production site and should backup the original scripts. You should always comment your code so you know what has been changed. Care should also be taken during upgrades in the code to make sure things are not broken (like conflicts during a CVS update).

Having said that, these patches are among the simplest and the recovery from an error is easy: simply replace the file with original from the core distribution.

===Moodle Forms Overview===

Rather than placing HTML form elements directly on the page, most well-written Moodle code will use the Forms Library. This allows a standard way to create user input elements and also centralizes code making it easier to override certain behaviors creating a greater consistency.

An entire form is an "object" with methods and attributes. In many places in the Moodle code, the instance of the object is identified my the variable $mform, but you can use any variable.

Common methods of the form object look like:

* $mform->addelement(<elementtype>,<elementidentifier>,<displayname>,<options>);

This creates a new input element on a page.

While forms can be produced in any scripting page which outputs code, you will often find code for printing out forms in a file like mod_form.php or in index.php of the affected component. The examine the URL of the page being viewed as a starting point for finding the file to be changed.

Always comment your code so you can change or remove it later.. For single line modifications, considering putting in your new code, and then and it with //<yourusername> <date> <the old code>. This allows for retention of eisting line numbers.

==Changing defaults==

The '''setDefault''' method is used to establish the initial value used in the form and allows you to to define the most common setting for use in your institution.

Example: Change the default number of points for a default assignment from 100 points to 10 points.

Solution:

In the file /mod/assignment/mod_form.php, find

$mform->setDefault('grade', 100);

Change the default to 10, and comment out the previous code with your initial and dates:

$mform->setDefault('grade', 10); //GVA 20080608 $mform->setDefault('grade', 100);

==Hiding fields==

Form elements are created for a page using the '''addElement''' method. Various types of element are text, select, date_time_selector, htmleditor, etc.

There is also the type "hidden" that defines the element on a page and allows you to set a default value, stores previous values from a submission etc. To simplify your forms for you users, simply change the type of the field during when addElement is called to hidden.

Example: Your site does not want to use meta courses and you want to remove it from the course creation/edit page. In the file /course/edit_form.php

Change:

$mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

to

$mform->addElement('hidden', 'metacourse', get_string('managemeta'), $meta); //GVA 20080610 $mform->addElement('select', 'metacourse', get_string('managemeta'), $meta);

==Setting fields to "Advanced"==

For elements that are infrequently used in your institution, you can still simplify the interface while making options still available to your 'Power Users' by marking elements as "advanced".

These elements only appear to the user when the click the "Set Advanced" button.

To identify the element as advanced, call the '''setAdvanced''' method after the element has been created.

Example:

Your typical user is local and hence it will be rare that they will use a different time zone. To clean up the interface, set the option to change the user time zone so that it is shown only when the user clicks "Set Advanced".

Solution:

In the file /user/editlib.php, find:

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);

Set the field to advanced using the setAdvanced method

$mform->addElement('select', 'timezone', get_string('timezone'), $choices);
$mform->setAdvanced('timezone');

Patching forms tutorial

2008-06-10T08:32:36Z

Ganderson: /* Hiding fields */

Patching forms tutorial

2008-06-10T08:03:43Z

Ganderson: /* Changing defaults */

Patching forms tutorial

2008-06-10T07:46:29Z

Ganderson: /* Moodle Forms Overview */

Talk:Repository API

2008-06-10T07:40:14Z

Ganderson: "local repository name"

(Ideas will be deleted from the comments section as they are resolved or merged into the main spec)

===Missing concept of trusted files===
Files are not created equal, some of them are to be trusted, some can not be trusted at all. Web browsers trust everything received from the server, files from server may access cookie information and thus scripting technologies may allow them to do anything user can do. We do have to trust our teachers because they are supposed to create the learning content, but we definitely can not trust all students.

Imagine if students were allowed to upload arbitrary files to server, like html file loaded with javascript and the server would happily serve them to all Moodle users. Our solution is to use html cleaning filters for submitted texts and force downloads of student uploaded files. To do this we must know if we trust the files or not. Unfortunately the forced downloads of student uploaded files and cleaning of html texts does not solve all problems, because bugs in browsers and especially browser plug-ins may sometimes be used to work around our protections.

The best solution would be to use separate web addresses for trusted and not trusted files (two wwwroots in config.php), not all sites may afford two different addresses but we should be imo prepared for this. [[User:Skodak|Skodak]] 16:42, 28 February 2008 (CST)

Great idea, yes. In fact couldn't all the files be served via $CFG->fileroot all the time?
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

userid field could be used for this, but separate flag might be better in order to allow teachers to upload untrusted files (teacher uploads assignment submission for the student).

===Relative file links===
Flash, Java and SCORM require relative links and directory hierarchy in general - we must support it. Some SCORM packages load hundreds of files per page which means the file serving must be very fast with minimum of db access.

Reading the proposal above it seems the API is about serving of isolated files referenced by repository ids. HTML requires to use relative or absolute locators with file names, we can not use repository ids directly in relative links. In case of scorm we have absolute path to base of SCORM package of given activity and SCORM files use relative links inside the package.
Solution could be to store relative paths directly in filename field ex:directory1/directory2/filename.ext.

Yes I agree, we definitely need to support (virtual) directories and slasharguments.
We could just match the file argument to a path in the db. Perhaps add the fileid
to the argument path as a primary key: fileid/directory1/directory2/filename.ext
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Virtual directories and files===
Sometimes the content of files is generated on the fly (csv exports, etc.), there are many special files spread through codebase doing nearly the same, it should be imho possible to use the same file API for these.

Another virtual example is assignment submissions and webdav. I would like to see an option to browse the assignment submissions as directory structure, the top directory would be a list of names of users, inside html files with online assignment and uploaded files. This would allow us to implement simple zip&go or webdav based offline grading solutions. The problem here is that the content of this virtual submissions directly needs to be created on the fly based on user references, the proposed repository structure can not be used for this.

Very interesting idea! [[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Backup/restore relinking===
We are supporting relinking inside courses only. Till now it was easy to guess if absolute link will work after restore on another server.
There are several types of files:
*course files - relinked during restore, works on any server if from the same course
*module files - not relinked, urls are not permanent, link can not be copypasted (assignments, forum attachments, rss files, etc.)
*user files - not relinked, links work only on original server (blog attachments, personal files, etc.)

I think all this will be simplified in the proposed system because everything is
represented using the same system: a file with an ACL (backup can quickly
determine all the files in one course, probably using one SQL query).
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

If we are backing up/restoring on the same server, will copies of a course restore without file duplication? I use this a lot so that I can archive one year's course whilst modifying it for next year. [[User:Matt Gibson|Matt Gibson]] 03:12, 29 April 2008 (CDT)

===Access needed for both file and its instances===
We need two types of access control - first who can create instances (link files), second who can access the instance (download the file).

For the first don't we already have those capabilities? (like mod/forum:createattachment,
moodle/course:managefiles) but they probably could use rationalising. We'll need new
ones per repository, too, of course.
[[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

===Cache lifetime===
There should be a way to specify cache filetime for each instance of file. For example 0 for uploaded assignments, 1 day for resource file. It might be better to allow modules to decide about this, at present it is hardcoded in file.php.

Great idea. [[User:Martin Dougiamas|Martin Dougiamas]] 07:08, 29 February 2008 (CST)

== Hierarchy in tables ? ==

It's possible that I don't undertand a key piece of the concept, but I wonder why there is no reference to any "parent id" in the file or file_instance table ?
In other words, how the hierarchical structure is supposed to be "imported" from repository to Moodle ?
If the hierarchy is reserved to the course context, and not to the repository context, it seems difficult to allow students to access
to a complete directory, for example.

On the other hand, maybe it's only a question for the "local" repository type, and not to the "generic" repository API ?
[[User:Allegre Guillaume|Allegre Guillaume]] 16:43, 5 March 2008 (CST)

[[User:Martin Dougiamas|Martin Dougiamas]] 12:58, 15 March 2008 (CDT): basically I was thinking we just store a full local path for each file instead of hierarchies. It wasn't in the db schema though: I've just added it. Thanks!

As for allowing access to a whole directory, that's something I've not thought about - thanks! I agree we need to support something like that in the interface. Hmm ..

== Editing Repository Files / Version Control ? ==

How do you imagine to handle the "editing file" problem ?
I can see several solutions :
# the simplest way : write access to a file really allows to edit (re-upload) the file, each instance being modified
# the "cheap copy" way : optionally, the modification is applied only to new file_instances (or those for which the teacher forces to). Here you have to handle two (then maybe more) revisions of this file.
This triggers the file revisions (or version control) question.

A related question is about versionned files :
should it depend only upon the repository layer (for example, a plugin could implement a SVN "repository") ?
Or should Moodle be aware of the file "revision number" ?
[[User:Allegre Guillaume|Allegre Guillaume]] 17:00, 5 March 2008 (CST)

[[User:Martin Dougiamas|Martin Dougiamas]] 13:08, 15 March 2008 (CDT): I don't think we should start getting into such things, version and editing is the job of the dedicated external repository system and people should use that interface.

What we do have in Moodle is the file->updates field. This specifies when to get a fresh copy. It would be set when the user has specified they want Moodle to use the "latest version" of the file. And if the user specified a particular version in the repository interface then that is what gets copied (once) and the file->updates field is left as zero.

One scenario would be if someone wants to use version 1 in one course and version 2 in another, but since the version is in the URL to the original file (and thus a different remote path) they would be treated as two separate files in Moodle anyway.

Might be a small problem if they said "latest version, no update" in course 1 and then later on said "latest version, no update" in a second course. I guess that would re-download the latest version (which might have changed) and thus course 1 would have an unexpected update. We could solve this by alerting the user and giving them a choice, I suppose.

== Replacing Moodle's File System ==

The API as specified still uses the standard Moodle file system, which has its limitations while providing a simple file access method. But, shouldn't we also be considering completely (or partially) replacing the Moodle file system with the repository system? To that end, the file interface would be the same to users, but where the files are and how they are accessed would be up to which repository was being used. In this system, the standard Moodle file system would just be one of the available repositories. Then the API could support more robust access controls if available, or very few (as Moodle does now). This could allow for per-directory / per-file privilege granting, common file areas so that courses could access the same copy of a file (rather than copying it into the Moodle file area), etc.

The API could also support multiple repositories and allow choosing a file as a link rather than copying it.

Of course, this would also mean allowing write access to the repository area from Moodle, rather than leaving it as read-only. I know the plan was to do this through the [[Portfolio API]], but that really is limited to a user storage function and not a file management function. I think having an API defined to allow for full file management would be a better solution - even if not supported by all repositories.
[[User:Mike Churchward|Mike Churchward]] 12:54, 6 March 2008 (CST)

[[User:Martin Dougiamas|Martin Dougiamas]] 12:54, 15 March 2008 (CDT) :
Actually, Mike, the standard file system is NOT being retained at all. I've clarified this slightly in the docs. The course-centered structure for files is gone. All files ARE stored on disk but most of the info regarding their location and access is all governed by a table in the database (so the files could just as easily be in a remote database if you wished). Files used in multiple areas within Moodle will never be stored more than once in Moodle.

The idea of a read/write interface was how we started, but it's insanely complex once you try to handle backups (ie how do you make a complete backup suitable for giving to someone else?) and access control (how do you decide access depending on Moodle contexts), and we'll never do it as well as the original repository does it. Why should we duplicate the Hive interface (to use an example) in Moodle when Hive has a perfectly good one already, one that handles all the extra stuff like Copyright controls, workflow and so on?

That said, the current Repository plugin idea is very simple, so that if anyone really wanted to embed management into the "file picker" interface they totally could do it in the plugin.
---

==Windows network drives==
I've added this to the end of the list of repository types to be supported because its possibly the most useful one I can think of. Our school wants to make the transition to moodle, but getting the files on there is the biggest barrier and there is a lot of stuff sitting on our shared and personal folders which is time consuming to transfer. Integration is a big thing that management want to see, particularly the ability to bulk upload files. This may not be a repository as such because it may be that the best way is to copy the file from the shared folder into the repository rather than where it is so it can be moved/deleted accidentally, but easy access is vital in making the process of uploading a file possible. It would also make Moodle a killer app in that it could make our network drives available from home through a secure web interface.

I've linked to Guy Thomas' [http://moodle.org/mod/data/view.php?d=13&rid=991 Windows Share Web Client block] as it is a good start, but sadly only works on Linux. [[User:Matt Gibson|Matt Gibson]] 03:43, 29 April 2008 (CDT)

Fantastic idea, let's call it the SMB plugin - [[User:Martin Dougiamas|Martin Dougiamas]] 21:25, 8 June 2008 (CDT)

==Bulk operations==
On a similar note, Don Hinkelman's new course format provides a great bulk-upload feature whereby a whole folder can be uploaded and added to the course as resources with the names of the files as titles, with just a couple of clicks. I know this is extending the repository idea a little, but to be honest, I think that one of the biggest weaknesses of Moodle's file handling right now is not being able to add an entire folder of files without manually going through each one and laboriously specifying location and title. To make any repository useful, I think three operations should be possible with one or two clicks:
* Add a whole folder/group of files to the repository at once
* The above operation, but additionally, have all of the folder/group added to a course and named automatically, all in one go.
* Find a group of files which are already in the repository and add them to a course all at once, with automatic naming as above.
Not sure if this is best put here or in the Developemt: File_API bit, but here seemed slightly better. [[User:Matt Gibson|Matt Gibson]] 03:43, 29 April 2008 (CDT)

This is probably not related to the file API at all. I'd see it as being a new item on the resource menu (Add multiple resources ...) with some sort of shift-click scenario. nice idea though. Can you file it as a tracker item? [[User:Martin Dougiamas|Martin Dougiamas]] 21:26, 8 June 2008 (CDT)

== Bulk and a new resource type from repository ==

Our school has several campuses and a distance learning unit with well organized and big course resource trees. The repository module could be enormously useful for us.

I have looked at Moodle's IMS repository a bit, and like the way it is possible to put multiple resources into one access point. If the new repository could have some of the same possibilities, it would be marvellous. The drawback with the IMS is that it opens a new window with all the multiple resources. Instead, it would be OK to be able to share a whole lot of resources, or a whole "resource tree".

I also like the bulk function, to be able to parse a folder of say, html-files, and add it to the resource tree.

==Further notes==

* WebDAV --[[User:Helen Foster|Helen Foster]] 17:20, 9 June 2008 (CDT)

== "local repository name" ==

I think users will find the word local to be confusing. For the developer or administrator, local seems to refer to the Moodle server. But for the teacher or student, they will think that local refers to their own local files system. I would suggest just using the domain name for that server (like myMoodleSite.org) and list it as the first entry to avoid this confusion. [[User:Gary Anderson|Gary Anderson]] 02:40, 10 June 2008 (CDT)

Patching forms tutorial

2008-06-09T14:57:47Z

Ganderson: Continued update of draft

Patching forms tutorial

2008-06-08T14:31:18Z

Ganderson: Start of page for patching forms

by Gary Anderson

One of the easiest local modifications that an institution can make to customize their Moodle site is to make simple modifications to the form elements that appear on pages. This tutorial will demonstrate how to do such modifications including changing default values, hiding elements so they are not available to users, and setting elements to "advanced" so that the user sees it only if they click on the "show advanced" button.

==Warning==
Making custom changes to the PHP scripting code in Moodle should be done carefully. You should always test your code before using it on your production site and should backup the original scripts. You should always comment your code so you know what has been changed.

Having said that, these patches are among the simplest and the recovery from an error is easy: simply replace the file with original from the core distribution.

==Moodle Forms Overview==

==Changing defaults==

==Hiding fields==

==Setting fields to "Advanced""

Seattle Academy

2008-04-15T11:02:21Z

Ganderson: Added Assignment default patch and minor edits

=Seattle Academy=
Seattle Academy is an independent secondary school of approximately 580 students. The upper school has had a laptop program for all students since 1997 and has used Moodle since 2005. The school used and modified version 1.6 until Moodle 1.9 was in Beta, and then made bug fixes and usability recommendations prior to 1.9 going final. Here we document additional customizations to Moodle 1.9 that are not yet part of the core Moodle code.

These patches and custom blocks are by [https://docs.moodle.org/en/User:Gary_Anderson Gary Anderson], except where noted. The day-to-day operation of the Moodle server is now handled be the technology department of the school allowing Gary to focus more time both on teaching with Moodle and on sharing his code and expertise with others.

TO DO: ADD GRAPHICS AND FORMAT BETTER

==Custom Blocks==

* '''Assignments to grade block''': A block that reports to teachers those assignments that need grading, including those where the due-date has past, where the student has made a submission not yet graded, or where students have made a revision. It works with the school's custom due-date code.
* '''Problem assignments block''' Reports to a student assignments in their classes that have "problems", such as a due-date that has past without a submission, the case where a teacher makes a comment but no grade, the case where a teacher has given a grade of zero, etc.
* '''Advisee problem assignments block''' For a list of an adviser's students, reports the number of "Problem assignments" with a list of issues.
* '''Major assignments block''' Teachers can categorize an assignment as "major". This block lists out by date and graduation year with the student count of the number of students affected all such assignments that are marked as major (like big tests, projects, etc.) This allows teachers to avoid conflicts.
* '''View Submissions block''' This block allows you to select an assignment and it prints a report of all the student's submissions on one page. This allows a teacher to assign a reflection on a day's work and quickly assess student problems, issues they want to talk about, who has done the work, etc.
* '''Customized Attendance block''' A custom version of Dmitry Pupinin's attendance block which ties in with our school's attendance database so a teacher, when taking attendance on Moodle, will know if the student is listed as having an excused absence, early dismissal, etc.
* '''MoodleHacks Patcher block''' This block inserts and removes custom patches that Gary has written. This allows features to be added and removed much more easily than custom CVS or SVN patches. It also makes the patches more compatible with CVS updates to core by reducing conflicts: patches are typically single-line insertions.

==Custom Patches==
* '''Alternate due dates patch''' Allows different due dates to be set, based on the group that the student is in. This allows the same course to be taught to multiple sections with the correct due date for each student.
* '''Autograding patch''' Assignments are marked as full credit if submitted on time, and get prorated credit during a grade interval, and a zero after that interval has past. The grade is subject to instructor review, and is marked as such. But it allows for much easier grading for those types of assignments that get full credit if submitted on time.
* '''Course page assignment status for students patch''' Marks the status of assignment on the course page with words like "Past due", "Zero", "See Comment", "Graded", etc. Assignments marked in red are "Problem assignments" that the student should deal with.
* '''Decimal grading patch''' Allows assignments to be graded with decimal rather than just integer grades. So, an assignment can be given a score of 98.3, etc. Karlene Clapp has modified this to allow such grades to be entered on the assignment submission page and to have an "exempt" checkbox.
* '''Gradebook tabs patch''' Brings back the tabs in the 1.9 gradebook so that teachers can quickly go between the grader report, preferences, categories and items, grade report, etc. This was posted as a patch to the tracker but not implemented.
* '''Course page assignment status for teachers patch''' Marks the status of assignments on the course page including the number to be graded in red. This works with the Alternate due dates patch so it correctly counts only those that are due for a particular group.
* '''Gradebook report patch''' Allows teachers in the grader report to click on a student's name and see just that line (helpful when seeing the gradebook with the student). Students can also see this line in the grader report.
* '''Quiz results filter patch''' Allows teacher to filer out only graded/ungraded attempts in manually graded essay quiz items.
* '''Course defaults patch''' Simplifies the course settings and sets defaults (such as start date, groups, etc.) that work best for the school.
* '''Course due dates patch''' Prints the due dates of assignments on the course page. This works with our Alternate due date patch so it prints the correct due date and time for a given group.
* '''Weeks order patch''' Allows a user to view a course page so that the current week is the first one and previous weeks are shown in descending order (or they can use the menu to show the classic view). Preferences are stored per user based on their last view.
* '''Setting grading category patch''' While this patch was submitted and implemented in core, this patch still allows the part that was not implemented: setting the category on the grading page.
* '''Quiz import (Blackboard/Examview) patch''' Allows Examview (a test generating package) to import into gradebook using the Blackboard format. Previously this worked with only text based questions; this patch allows for the import of questions that include graphics, etc.
* '''Gradebook Patch misc patch''' A serious of miscellaneous patches that make the gradebook easier for 1.9 in the secondary school setting, including better defaults, more hidden items, etc. These are essentially what remains that was not implemented from Gary's suggestions in tracker during the 1.9 beta process. Karlene Clapp, server administrator, has also added a patch to highlight a row, give alternate highlighting, and print student names on the right hand side.
* '''Assignment type change patch''' Allows a teacher to change the type of an assignment after it has been created (like from offline to upload or advanced upload, etc.
* '''Over maximum grade patch''' Allows grades to be entered that are over 100%
* '''IMAP bypass''' Allows the MD5 hash of the password to be used for comparison in logging in, meaning that the Moodle server is not dependent on the mail server being up to operate. It also speeds up loggins.
* '''Major assignment selector patch''' Allows teachers to mark an assignment as "major" which puts it in bold on the course page and also lists it in the "Major assignments" block.
* '''Gradebook extra credit''' Allows an assignment or other grading item to be marked as extra credit so that the gradebook does not include it in the total points possible.
* '''Grade setting patch''' Puts a button on the assignment grading page for setting all remaining grades to Max, or to Min grade. This greatly speeds grading in cases where most assignments receive the same mark (if submitted), or when zero needs to be given to a batch of unsubmitted assignments, etc.
* '''Choice election mode patch''' Allows setting the choice module for a particular choice instance so that a course teacher will not see individual students choices. This is especially nice for providing anonymity during online elections.
* '''Assignment default patch''' Changes defaults and simplifies interface for teachers creating assignments so that common settings are given by default and little used features are hidden or treated as "advanced".

Seattle Academy

2008-04-15T00:44:17Z

Ganderson: Descriptions of customizations to Seattle Academy's Moodle

=Seattle Academy=
Seattle Academy is an independent secondary school of approximately 580 students. The upper school has had a laptop program for all students since 1997 and has used Moodle since 2005. The school used and modified version 1.6 until Moodle 1.9 was in Beta, and then made bug fixes and usability recommendations prior to 1.9 going final. Here we document additional customizations to Moodle 1.9 that are not yet part of the core Moodle code.

These patches and custom blocks are by [https://docs.moodle.org/en/User:Gary_Anderson Gary Anderson], except where noted. The day-to-day operation of the Moodle server is now handled be the technology department of the school allowing Gary to focus more time both on teaching with Moodle and on sharing his code and expertise with others.

TO DO: ADD GRAPHICS AND FORMAT BETTER

==Custom Blocks==

* '''Assignments to grade block''': A block that reports to teachers those assignments that need grading, including those where the due-date has past, where the student has made a submission not yet graded, or where students have made a revision. It works with the school's custom due-date code.
* '''Problem assignments block''' Reports to a student assignments in their classes that have "problems", such as a due-date that has past without a submission, the case where a teacher makes a comment but no grade, the case where a teacher has given a grade of zero, etc.
* '''Advisee problem assignments block''' For a list of an adviser's students, reports the number of "Problem assignments" with a list of issues.
* '''Major assignments block''' Teachers can categorize an assignment as "major". This block lists out by date and graduation year with the student count of the number of students affected all such assignments that are marked as major (like big tests, projects, etc.) This allows teachers to avoid conflicts.
* '''View Submissions block''' This block allows you to select an assignment and it prints a report of all the student's submissions on one page. This allows a teacher to assign a reflection on a day's work and quickly assess student problems, issues they want to talk about, who has done the work, etc.
* '''Customized Attendance block''' A custom version of Dmitry Pupinin's attendance block which ties in with our school's attendance database so a teacher, when taking attendance on Moodle, will know if the student is called listed as having an excused absence, early dismissal, etc.
* '''MoodleHacks Patcher block''' This block inserts and removes custom patches that Gary has written. This allows features to be added and removed much more easily than custom CVS or SVN patches.
* '''Choice election mode patch''' Allows setting the choice module for particular choice instance so that teacher can not see the way that individual students chose. This is especially nice for providing anonymity during online elections.

==Custom Patches==
* '''Alternate due dates patch''' Allows different due dates to be set, based on the group that the student is in. This allows the same course to be taught to multiple sections with the correct due date for each student.
* '''Autograding patch''' Assignments are marked as full credit if submitted on time, and get prorated credit during a grade interval, and a zero after that interval has past. The grade is subject to instructor review, and is marked as such. But it allows for much easier grading for those types of assignments that get full credit if submitted on time.
* '''Course page assignment status for students patch''' Marks the status of assignment on the course page with words like "Past due", "Zero", "See Comment", "Graded", etc. Assignments marked in red are "Problem assignments" that the student should deal with.
* '''Decimal grading patch''' Allows assignments to be graded with decimal rather than just integer grades. So, an assignment can be given a score of 98.3, etc. Karlene Clapp has modified this to allow such grades to be entered on the assignment submission page and to have an "exempt" checkbox.
* '''Gradebook tabs patch''' Brings back the tabs in the 1.9 gradebook so that teachers can quickly go between the grader report, preferences, categories and items, grade report, etc. This was posted as a patch to the tracker but not implemented.
* '''Course page assignment status for teachers patch''' Marks the status of assignments on the course page including the number to be graded in red. This works with the Alternate due dates patch so it correctly counts only those that are due for a particular group.
* '''Gradebook report patch''' Allows teachers in the grader report to click on a student's name and see just that line (helpful when seeing the gradebook with the student). Students can also see this line in the grader report.
* '''Quiz results filter patch''' Allows teacher to filer out only graded/ungraded attempts in manually graded essay quiz items.
* '''Course defaults patch''' Simplifies the course settings and sets defaults (such as start date, groups, etc.) that work best for the school.
* '''Course due dates patch''' Prints the due dates of assignments on the course page. This works with our Alternate due date patch so it prints the correct due date and time for a given group.
* '''Weeks order patch''' Allows a user to view a course page so that the current week is the first one and previous weeks are shown in descending order (or they can use the menu to show the classic view). Preferences are stored per user based on their last view.
* '''Setting grading category patch''' While this patch was submitted and implemented in core, this patch still allows the part that was not implemented: setting the category on the grading page.
* '''Quiz import (Blackboard/Examview) patch''' Allows Examview (a test generating package) to import into gradebook using the Blackboard format. Previously this worked with only text based questions; this patch allows for the import of questions that include graphics, etc.
* '''Gradebook Patch misc patch''' A serious of miscellaneous patches that make the gradebook easier for 1.9 in the secondary school setting, including better defaults, more hidden items, etc. These are essentially what remains that was not implemented from Gary's suggestions in tracker during the 1.9 beta process. Karlene Clapp, server administrator, has also added a patch to highlight a row, give alternate hilighting, and print student names on the right hand side.
* '''Assignment type change patch''' Allows a teacher to change the type of an assignment after it has been created (like from offline to upload or advanced upload, etc.
* '''Over maximum grade patch''' Allows grades to be entered that are over 100%
* '''IMAP bypass''' Allows the MD5 hash of the password to be used for comparision in logging in, meaning that the Moodle server is not dependent on the mail server being up to operate. It also speeds up loggins.
* '''Major assignment selector patch''' Allows teachers to mark an assignment as "major" which puts it in bold on the course page and also lists it in the "Major assignments" block.
* '''Gradebook extra credit''' Allows an assignment or other grading item to be marked as extra credit so that the gradebook does not include it in the total points possible.
* '''Grade setting patch''' Puts a button on the assignment grading page for setting all remaining grades to Max, or to Min. This greatly speeds grading in cases where most assignments receive the same mark, or when zero needs to be given to old assignments, etc.

Roadmap

2008-03-29T18:53:40Z

Ganderson: /* Hopefully */ Usability improvments

This roadmap collects the best information about upcoming features in Moodle. It is not 100% certain - features may change according to available funding and developers.

== Version 2.0 - Expected Late 2008 ==

(This list is fluid, depending on available resources)

===Definitely===
* Moodle 2.0 will require PHP 5.2 as a minimum, allowing us to clean up the code in some areas. For more info see: [http://gophp5.org/ gophp5.org].
* [[Development:Portfolio API|Portfolio API]] - Enovation.ie / Moodle.com
::Interface Moodle activities and repositories to help produce portfolios for internal assessment AND external publication. The first Portfolio plugin implemented will be [http://www.mahara.org/ Mahara].
* [[Development:Repository API|Repository API]] - Moodle.com
::Abstract all file operations to an API that allows plugins for different external repositories.
* [[Development:Conditional activities|Conditional activities]] - Moodle.com
::Allowing dependencies and forced paths through the content.
* [[Community hub]] interfaces - Moodle.com and others
::Makes it easy for users to find and navigate other systems and external Moodle repositories, leveraging the Moodle Network in various ways.
* Old DB install/upgrade system removed
:: The deprecated system for installing or upgrading database entries used in Moodle < 1.7 will be completely removed, while supporting only the new XML based database scheme introduced in 1.7.
* [[Feedback module]]
* [[NWiki roadmap|New Wiki]] module (nwiki) - DFWikiteam-UPC
* [[Development:Quiz_report_enhancements|Major improvements to the quiz reports]], especially regrading and item analysis. - The Open University
* Messaging improvements
* Secure RSS feeds

===Hopefully===
* [[IMS Learning Design]] - Moodle.com
::Support for importing/exporting LD, converting Moodle activities and sequences of activities into a standard format for sharing, and importing standard sequences into Moodle courses
* [[Student Information API]]
::API for integrating external systems for managing student information
* [[Development:Voice|Moodle Voice]]
:: Moodle Voice is a project for embedding VoiceXML support into Moodle Core.
* [[Learning Design export]]? - Moodle.com and Open University of The Netherlands
::We plan to have a very simple export for any Moodle course into IMS LD format, as a proof of concept and to help the community start learning about IMS LD.
* [[Turnitin Integration]] - Dan Marsden with support from Catalyst NZ
* Improve usability
:: Usability improvements for new and established users through increased field testing, selective feature availability, and research (such as the GSOC project).

==See also==

* [[Release Notes]]

[[Category:Developer]]

[[es:Planificación]]
[[fr:Planification]]

Seattle Academy

2008-01-22T05:53:16Z

Ganderson: /* Seattle Academy */ Update for settings to Beta 4

=Seattle Academy=
Seattle Academy is an independent secondary school of approximately 560 students. The upper school has had a laptop program for all students since 1997 and has used Moodle since 2005. Here we document how we have configured and customized Moodle 1.9 to best serve students and faculty in this environment.
Note: These are draft recommendations by Gary Anderson of Seattle Academy.
They will be reviewed for final consideration and implementation by our technology
staff in consultation with the other teaching faculty.
==Server Configuration==
===Default Settings===
These settings apply to Moodle 1.9 Beta4 which is still in development.
In some cases, the default settings may change and so some of these
customizations may not need to be changed and would be for reference only.
As we were early users of 1.9 on a school production server, a number of our
default suggestions have been applied to Moodle base code as as appropriate.
====Site Administration Block====
=====Grade category settings=====
* Hide forced settings - Yes
We like to keep the interface simple for teachers, so those settings that cannot be changed are not visible.
* Aggregation - Simple weighted mean of grades -- not advanced
This is not designated as advanced because teachers will want to set courses to "Weighted mean of grades" if they assign different weight to grading categories like "Daily Work" and "Exams".
Simple weighted mean of grades is probably better called "Average of points". It does the common computation of taking the number of points (or marks) earned divided by the number of points possible. This should not be confused with what is called "Mean of grades" which is probably better called "Average of percents". With this computation, grades are normalized to a percentage and then averaged.
* Aggregate only non-empty grades - Yes -- Advanced
If an activity is yet to be marked, it is not factored into the students grade. If the activity shoudl earn no credit, the teacher would give the activity a zero.
This would be marked No in the less common case that the teacher wanted activities to be given a score of zero until they are marked.
* Include outcomes in aggregation - No, Force,advanced
Our school does not use outcomes, so we hide these settings under an advanced setting. Since outcomes adds elements to the user interface for teachers and make the gradebook more complicated when used, we force it to hide the feature.
* Aggregate including subcategories - No, advanced
Having this featured turned on causes Mean of grades not compute grades if grading categories are used (unless every activity is manually given a grade).
* Keep the highest - none, advanced
This option is seldom used.
* Drop lowest - none, advanced
While this option is more common, we keep it as advanced to simplify the interface for most users.
=====Grade item settings=====
*Grade display type: Real
However, category summaries are normally percentages (including course summaries), so teacher must manually set these up when setting up their gradebooks.
Advanced grade item options: We use the defaults excpet for "Grade display type" which is set to not be advanced because teachers must set these for category and course summaries.

=====Scales=====
* Remove: Separate and Connected Way of Knowing
This must be here for historical reasons in Moodle's development. We don't know what it is and will not use it. This must be done before the scale is used in a course.
* Added: Not Submitted, Submitted
Seattle Academy faculty are expected to, at a minimum, let people know the status of a student's assignment submissions in Moodle. With this setting, activities can be marked as satisfactorily submitted or not. Potentially, submitted could be treated as 100% for that assignment and not submitted as 0%, so the percent of submitted assignments could be reported.
=====Grader report=====
* We use all the defaults except Column average display type is Percentage

===Custom patches to the code===
To do: Add this section. Seattle Academy has several dozen customizations to the Moodle code for the high school environment, in many cases posting them to Moodle tracker for future versions..
===Selection of blocks and modules===
===Custom blocks===
To do: Add this. We have a half-dozen custom blocks for reporting status on assignments, attendance, and other progress indicators to ease the use of Moodle in a high school environment.

Developer documentation

2008-01-13T03:40:03Z

Ganderson: /* Resources and tools */ Change cvs reference to new server

'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[New page name]]</nowiki></code>. If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches. A page may be added to the Developer category by typing <code><nowiki>[[Category:New page name]]</nowiki></code> at the bottom of the page.

==How Moodle development works==

This [[Overview|overview of the Moodle development process]] may be handy in understanding how the development of Moodle occurs and how people become Moodle developers.

==Guidelines==

The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers
*[[Moodle design goals]] spells out the basic design goals behind Moodle
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc
*[[Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes
*[[Unit tests|Unit tests]] explains how to run the unit tests, and how to write new test cases.

==Documentation for core components==

This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].

The documents below give a general overview. For detailed function-by-function documentation, see the [http://phpdocs.moodle.org/ phpDocumentor] documentation that is automatically generated from the comments in the code. And don't forget that the most up-to-date and detailed description of how the code works is the code itself, and you can [http://xref.moodle.org/nav.html?index.html browse the code online using phpXRef]. Moodle code should be easy to read and understand. Use the source, Luke!

===Core components that affect everything===

*[[Database schema introduction|The database schema]]
*lib/moodlelib.php
*[[lib/weblib.php|lib/weblib.php]] for outputting stuff.
*[[XMLDB_Documentation|Database abstraction layer]] @ v[[1.7]]
*[[Roles|Roles and Capabilities system]] @ v[[1.7]] for controlling who can do what.
*[[lib/formslib.php|Forms library]] @ v[[1.8]] for creating accessible and secure HTML forms that let users edit things.

===Core libraries with a more specific uses===

*[[Authentication API]]
*[[Cookieless Sessions]]
*[[Email processing]]
*[[Environment checking|Environment checking]] before install, check the user's server to ensure Moodle will work there.
*[[Groups|Groups system]]
*[[Grades|Gradebook]]
*[[Moodle Network|Moodle Network]]
*[[Question engine]]
*[[Stats package]]
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]
*[http://developer.yahoo.com/yui YUI JavaScript library] - YUI was selected as the official AJAX library for Moodle.
*[[lib/graphlib|lib/graphlib]]

===Modules included in the standard distribution===

*[[Quiz developer docs|Quiz module]]
*[[SCORM schema|SCORM module 1.5 schema]]

==How you can contribute==

===Make a new plugin===

The M in Moodle stands for modular, and the easiest, most maintainable way to add new functionality to Moodle is by using one of the many plugin APIs. There are many types of plugin you can write:
*[[Modules|Activity modules]]
*[[Admin reports|Admin reports]]
*[[Assignment types|Assignment types]]
*[[Authentication plugins|Authentication plugins]]
*[[Blocks|Blocks]]
*[[Course formats]]
*[[Course Report Plugins|Course reports]]
*[[Database fields|Database fields]]
*[[Database presets|Database presets]]
*[[Enrolment plugins|Enrolment plugins]]
*[[Filters|Filters]]
*[[Gradebook plugins|Gradebook plugins]]
**[[Gradebook report|Gradebook report]]
**[[Gradebook export|Gradebook export]]
**[[Gradebook import|Gradebook import]]
*[[Question engine|Question engine]]
*[[Question import/export formats|Question import/export formats]]
*[[How to write a quiz report plugin|Quiz reports]]
*[[Resource types|Resource types]]
*[[SSO plugins|SSO plugins]]
*[[Search engine adapters|Search engine adapters]]

When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 Moodle modules and plugins database].

===Change core code===

Some types of change can only be made by editing the core Moodle code. Such changes are much harder to maintain than plugins. If you want your core change to be considered for inclusion in the official Moodle release, you need to create an issue in the [[Tracker|tracker]], and attach your change as a [[How_to_create_a_patch|patch]]. It is also a good idea to discuss your ideas in the forums first.

===Ways to contribute that do not involve PHP programming===

*[[Themes|Create Moodle themes]]
*[[Translation|Translate Moodle into other languages]]
*[[MoodleDocs:Guidelines for contributors|Help document Moodle]]
*[[Database schemas|Database schemas]]
*[[Tests|Join the testing effort]], which involves [[Tracker|participating in the bug tracker]]

==Plans for the future==

Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.

Once ideas begin to crystallize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.

*[[Roadmap]]
*[[Developer notes|Developer notes]]
*[[Student projects]]
*[[Developer conferences]]

== Resources and tools ==

*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle
*[[Finding_your_way_into_the_Moodle_code|Finding your way into the Moodle code]] - also aimed at newcomers
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues
**[[Firefox tracker search]] - How to setup a firefox quicksearch to easily navigate to moodle bugs
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD
*Browse the code online:
**[http://cvs.moodle.org/moodle/ the code with a complete change history from CVS]
**[http://xref.moodle.org/index.html the code, with links generated by PHPXref]
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - compiled from the comment attached to each class and function in the code
*[[Database Schema|Database Schema]] - for recent releases
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course
**especially the [http://moodle.org/mod/forum/view.php?id=55 General developer forum]
**[[Filters used on the Moodle.org forums|cool tricks you can use in the moodle.org forums]]
*Some tools people use when working on Moodle code:
**[[Setting_up_Eclipse|Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.
**[[vim|Setting up Vim for Moodle development]]
**[[ctags|Ctags]] - Using a tags file to navigate code
**[[W3C_validation|W3C HTML validator]] - Moodle has built in support to make using it easier.
**Firebug plugin for Firefox.

==See also==

*[http://security.moodle.org/ Moodle Security Centre]
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services

[[es:Documentación para Desarrolladores]]
[[fr:Documentation développeur]]
[[zh:开发者文档]]
[[ja:開発者ドキュメント]]

User:Gary Anderson

2007-11-23T22:30:44Z

Ganderson: Added images and formated page

[[Image:GaryAndersonLava.jpg]]

Gary Anderson is a native of Seattle, a graduate of the University of Washington with degrees in Math, Business Economics, and certification in history education. He has a Master's degree in Teaching from Seattle University. Before entering teaching in 1996, he was the General Manager of the largest computer store in the Pacific Northwest which sold a majority of Apple II and Macintosh computers to schools, businesses and individuals around the I-5 corridor. He was also president of a software company that specialized in network communications.

Teaching is the family business for Gary. Both of his parents are retired teachers, and his brother is the principal of a middle school and his sister is an elementary school teacher.
His research interest is in the technology of instruction, and in particular the effects on student achievement when they receive rapid feedback on their performance. He has designed a number of software projects in advancement of this effort.

Gary is the head of the Math Department at Seattle Academy and incredible private, independent school that among many other things is in the 11th year of a universal laptop program for it's upper school. He teaches Advance Algebra, Second Year Calculus, and elective trimesters in Statistics, Math Modeling and Software Development. These math electives are the most popular electives in the school.

For the past 3 years, Gary has been known as the Moodle Master and has customized the software to make it especially usable in the high school environment. He is now turning over this responsibility to server administrator Karlene Clapp and Curriculum Technology Coordinator Vicki Butler so the he can focus on being more involved in the larger technology community, both contributing what he has learned from overseeing the school's Moodle project and to work on investigating best uses with the One Laptop per Child program among other things.

[[Image:GaryAndersonMoodleMaster.jpg]]

User:Gary Anderson

2007-11-23T22:17:38Z

Ganderson: Gary Anderson Bio

Gary Anderson is a native of Seattle, a graduate of the University of Washington with degrees in Math, Business Economics, and certification in history education. He has a Master's degree in Teaching from Seattle University. Before entering teaching in 1996, he was the General Manager of the largest computer store in the Pacific Northwest which sold a majority of Apple II and Macintosh computers to schools, businesses and individuals around the I-5 corridor. He was also president of a software company that specialized in network communications.
Teaching is the family business for Gary. Both of his parents are retired teachers, and his brother is the principal of a middle school and his sister is an elementary school teacher.
His research interest is in the technology of instruction, and in particular the effects on student achievement when they receive rapid feedback on their performance. He has designed a number of software projects in advancement of this effort.
Gary is the head of the Math Department at Seattle Academy and incredible private, independent school that among many other things is in the 11th year of a universal laptop program for it's upper school. He teaches Advance Algebra, Second Year Calculus, and elective trimesters in Statistics, Math Modeling and Software Development. These math electives are the most popular electives in the school.
For the past 3 years, Gary has been known as the Moodle Master and has customized the software to make it especially usable in the high school environment. He is now turning over this responsibility to server administrator Karlene Clapp and Curriculum Technology Coordinator Vicki Butler so the he can focus on being more involved in the larger technology community, both contributing what he has learned from overseeing the school's Moodle project and to work on investigating best uses with the One Laptop per Child program among other things.

Seattle Academy

2007-11-23T18:41:17Z

Ganderson: /* Site Administration Block */ Grader report defaults

=Seattle Academy=
Seattle Academy is an independent secondary school of approximately 560 students. The upper school has had a laptop program for all students since 1997 and has used Moodle since 2005. Here we document how we have configured and customized Moodle 1.9 to best serve students and faculty in this environment.
Note: These are draft recommendations by Gary Anderson of Seattle Academy.
They will be reviewed for final approval by our technology people in consultation
with the other teaching faculty.
==Server Configuration==
===Default Settings===
These settings apply to Moodle 1.9 beta2 which is still in development.
In some cases, the default settings may change and so some of these
customizations may not need to be changed and would be for reference only.
====Site Administration Block====
=====Grade category settings=====
* Hide forced settings - off
While this may be a useful setting for institutions that have uniformity in grading practices (as it could simplify the choices), our school, like most, give faculty considerable freedom in determining grading standards, hence we do not hide forced settings, using the default settings instead to ease course setup.
* Aggregation - Simple weighted mean of grades -- not advanced
Moodle core developers have come up with a new method of calculating grades, and call it mean of grades and have set it for the 'out of the box' default. It essentially converts each activity or graded item to a percentage before determining averages. Hence a 100 point assignment is worth the same as a 10 point assignment.
Simple weighted mean of grades does the more common computation for schools of having the average be determined as point earned over points possible, hence it is the mean of points as opposed to the mean of percentages. We rename these strings accordingly.
* Aggregate only non-empty grades - yes -- not advanced
Again, Moodle core developers have set the rather unusual 'out of the box' setting of treating all ungraded items as zero, rather than just not factoring these items into the grade. The means that most students will see a very low average until all items (including those not due yet are graded, typically at course completion.
The change of the setting to yes means that averages are only calculated on items that have been graded; teachers put in a score of zero when they want that computed into the grade.
Note: We are urging Moodle core reconsider the decisions prior to 1.9 going gold.
* Include outcomes in aggregation - no, advanced
Our school does not use outcomes, so we hide these settings under an advanced setting
* Aggregate including subcategories - yes, advanced
We typically don't anticipate the need for subcategories, but if a teacher uses them, they will probably divide things link homework into "first-half" and "second-half", so including these in the overall average seems appropriate.
* Keep the highest - none, advanced
* Drop lowest -none, advanced
=====Scales=====
* Remove: Separate and Connected Way of Knowing
This must be here for historical reasons in Moodle's development. We don't know what it is and will not use it.
* Added: Not Submitted, Submitted
Seattle Academy faculty are expected to, at a minimum, let people know the status of a student's assignment submissions in Moodle. With this setting, activities can be marked as satisfactorily submitted or not. Potentially, submitted could be treated as 100% for that assignment and not submitted as 0%, so the percent of submitted assignments could be reported.
=====Grader report=====
* Students per page - 100
Classes at Seattle Academy or normally under 20, but sometimes multiple sections brings the number higher; our largest is our Chemistry class with about 90 students. This setting lets a teacher view all grades at once without scrolling, and does not have too serious of an impact on the server.
* Grades Selected for Column Average -- Non-empty grades
This is an important setting as otherwise averages for assignments only make sense when all grading is completed, otherwise assignments not yet graded or those coming due later count as zero. Recommendation: This default for Moodle as it ships should be reconsidered.
* Show column averages: Yes. This is a common enough setting so the teacher can see how the class did on an assignment.
* Show number of grade in average: yes
Especially with the above settings, having a count of graded assignments is helpful.

===Custom patches to the code===
===Selection of blocks and modules===
===Custom blocks===

Seattle Academy

2007-11-23T18:24:09Z

Ganderson: /* Grade category settings */ Standard scale settings

=Seattle Academy=
Seattle Academy is an independent secondary school of approximately 560 students. The upper school has had a laptop program for all students since 1997 and has used Moodle since 2005. Here we document how we have configured and customized Moodle 1.9 to best serve students and faculty in this environment.
Note: These are draft recommendations by Gary Anderson of Seattle Academy.
They will be reviewed for final approval by our technology people in consultation
with the other teaching faculty.
==Server Configuration==
===Default Settings===
These settings apply to Moodle 1.9 beta2 which is still in development.
In some cases, the default settings may change and so some of these
customizations may not need to be changed and would be for reference only.
====Site Administration Block====
=====Grade category settings=====
* Hide forced settings - off
While this may be a useful setting for institutions that have uniformity in grading practices (as it could simplify the choices), our school, like most, give faculty considerable freedom in determining grading standards, hence we do not hide forced settings, using the default settings instead to ease course setup.
* Aggregation - Simple weighted mean of grades -- not advanced
Moodle core developers have come up with a new method of calculating grades, and call it mean of grades and have set it for the 'out of the box' default. It essentially converts each activity or graded item to a percentage before determining averages. Hence a 100 point assignment is worth the same as a 10 point assignment.
Simple weighted mean of grades does the more common computation for schools of having the average be determined as point earned over points possible, hence it is the mean of points as opposed to the mean of percentages. We rename these strings accordingly.
* Aggregate only non-empty grades - yes -- not advanced
Again, Moodle core developers have set the rather unusual 'out of the box' setting of treating all ungraded items as zero, rather than just not factoring these items into the grade. The means that most students will see a very low average until all items (including those not due yet are graded, typically at course completion.
The change of the setting to yes means that averages are only calculated on items that have been graded; teachers put in a score of zero when they want that computed into the grade.
Note: We are urging Moodle core reconsider the decisions prior to 1.9 going gold.
* Include outcomes in aggregation - no, advanced
Our school does not use outcomes, so we hide these settings under an advanced setting
* Aggregate including subcategories - yes, advanced
We typically don't anticipate the need for subcategories, but if a teacher uses them, they will probably divide things link homework into "first-half" and "second-half", so including these in the overall average seems appropriate.
* Keep the highest - none, advanced
* Drop lowest -none, advanced
=====Scales=====
* Remove: Separate and Connected Way of Knowing
This must be here for historical reasons in Moodle's development. We don't know what it is and will not use it.
* Added: Not Submitted, Submitted
Seattle Academy faculty are expected to, at a minimum, let people know the status of a student's assignment submissions in Moodle. With this setting, activities can be marked as satisfactorily submitted or not. Potentially, submitted could be treated as 100% for that assignment and not submitted as 0%, so the percent of submitted assignments could be reported.

===Custom patches to the code===
===Selection of blocks and modules===
===Custom blocks===

Seattle Academy

2007-11-23T18:04:32Z

Ganderson: /* Grade category settings */

Seattle Academy

2007-11-23T18:00:35Z

Ganderson: /* Server Configuration */ Draft notice

Seattle Academy

2007-11-23T17:54:04Z

Ganderson: /* Seattle Academy */ Begin Default Settings discussion

Seattle Academy

2007-11-23T16:25:33Z

Ganderson:

lib/formslib.php Form Definition

2007-10-28T11:46:20Z

Ganderson: /* textarea */ intro changed to introduction to not conflict with earlier button

{{Formslib}}
==definition()==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'

definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.

The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a legend.

<pre>
//-------------------------------------------------------------------------------
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</pre>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<pre>
$mform->closeHeaderBefore('buttonar');
</pre>

==addElement==

Use the addElement method to add a an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
===button===

<pre>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</pre>

A button element. If you want a submit or cancel button see 'submit' element.

===checkbox===
<pre>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</pre>
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

===choosecoursefile===
<pre>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));

</pre>

Choose a file from the course files area. The fourth option is a list of options for the element.

<pre>
array('courseid'=>null,\\if it is null (default then use globabl $COURSE
'height'=>500,\\ height of the popup window
'width'=>750, \\ width of the popup window
'options'=>'none');\\options string for the pop up window
\\eg. 'menubar=0,location=0,scrollbars,resizable'

</pre>

===date_selector===
<pre>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</pre>

This is a date selector. You can select a Day, month and year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true);
</pre>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===date_time_selector===
<pre>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</pre>
This is a group of select boxes to select a date (Day Month and Year)and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); The fourth param here is an array of options. The defaults for the options are :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true, 'step'=>5);
</pre>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===file===

File upload input box with browse button. In the form definition type
<pre>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</pre>

after form submission and validation use
<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</pre>

If you need advanced settings such as required file, different max upload size or name of uploaded file
<pre>

$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</pre>

<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</pre>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

===hidden===
<pre>
$mform->addElement('hidden', 'reply', 'yes');
</pre>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

===htmleditor & format===
<pre>

$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</pre>
You can supply a fourth param to htmleditor of an array of options :

<pre>
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65,
'width'=>0,'height'=>0, 'course'=>0);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</pre>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

===radio===
<pre>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</pre>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'submit' type element is a submit type form element which will submit the form. A Reset will not submit the form it will reset any changes the user has made to form contents. A cancel element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset') this avoids problems in javascript of collisions between form element names and names of javascript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameters allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use css instead of using attributes for styling.

A format element can be used as a format select box. It will be non selectable if you're using a html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==setHelpButton==
<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.

''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

[[Category:Formslib]]

lib/formslib.php Form Definition

2007-10-28T11:11:18Z

Ganderson: /* radio */ Fixed error in naming radio buttons

{{Formslib}}
==definition()==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'

definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.

The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a legend.

<pre>
//-------------------------------------------------------------------------------
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</pre>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<pre>
$mform->closeHeaderBefore('buttonar');
</pre>

==addElement==

Use the addElement method to add a an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
===button===

<pre>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</pre>

A button element. If you want a submit or cancel button see 'submit' element.

===checkbox===
<pre>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</pre>
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

===choosecoursefile===
<pre>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));

</pre>

Choose a file from the course files area. The fourth option is a list of options for the element.

<pre>
array('courseid'=>null,\\if it is null (default then use globabl $COURSE
'height'=>500,\\ height of the popup window
'width'=>750, \\ width of the popup window
'options'=>'none');\\options string for the pop up window
\\eg. 'menubar=0,location=0,scrollbars,resizable'

</pre>

===date_selector===
<pre>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</pre>

This is a date selector. You can select a Day, month and year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true);
</pre>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===date_time_selector===
<pre>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</pre>
This is a group of select boxes to select a date (Day Month and Year)and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); The fourth param here is an array of options. The defaults for the options are :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true, 'step'=>5);
</pre>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===file===

File upload input box with browse button. In the form definition type
<pre>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</pre>

after form submission and validation use
<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</pre>

If you need advanced settings such as required file, different max upload size or name of uploaded file
<pre>

$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</pre>

<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</pre>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

===hidden===
<pre>
$mform->addElement('hidden', 'reply', 'yes');
</pre>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

===htmleditor & format===
<pre>

$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</pre>
You can supply a fourth param to htmleditor of an array of options :

<pre>
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65,
'width'=>0,'height'=>0, 'course'=>0);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</pre>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

===radio===
<pre>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</pre>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'submit' type element is a submit type form element which will submit the form. A Reset will not submit the form it will reset any changes the user has made to form contents. A cancel element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset') this avoids problems in javascript of collisions between form element names and names of javascript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameters allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use css instead of using attributes for styling.

A format element can be used as a format select box. It will be non selectable if you're using a html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'intro', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==setHelpButton==
<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.

''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

[[Category:Formslib]]