MoodleDocs - User contributions [en]

Talk:Extending the theme custom menu

2020-10-01T13:19:34Z

Libertymoodle: /* Restrict menu options by Moodle Roles */

In the renderers.php file (in my project) I had to add the php tags <?php ?>, because they were missing on the original text. Fixed my problem, but I'm not sure whether I should edit the original post.
-----

Is it possible to add options to the custom menu that are only visible to people who have a certain role in Moodle? If so, can the details be added here?
--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 13:19, 1 October 2020 (UTC)

Course module

2020-06-24T06:34:23Z

Libertymoodle: /* url */

==Summary==
A course module (often abbreviated 'cm') represents each of the activities and resources found in a course. It contains information about which course and section the activity / resource is displayed on, as well as details about the visibility, group and completion status of the activity.

==Database tables==
The data for the course module is stored in the database table 'mdl_course_modules' (the 'mdl_' part will be different if you have chosen a non-default prefix for your database tables). The fields in this table link it to a number of other tables in the database.
* The 'course' field links to the 'mdl_course' table, which contains everything you need to know about a course.
* The 'module' table links to the 'mdl_modules' table, which gives information about the type of the module (e.g. 'quiz', 'resource') as well as its current version number.
* After looking up the type of the module, the rest of the details about this module can be found by looking up the 'instance' value (from the 'mdl_course_modules' table) in the 'mdl_{type}' table. Here you can find the name and introductory paragraph for the activity / resource, as well as information that is specific to the type of activity being looked at.

You can quickly gather all of this information, by using the 'get_fast_modinfo($course)' function. The easiest way to understand the data returned is to use the following code:
<code php>
global $DB;
$course = $DB->get_record('course', array('id' => $courseid));
$info = get_fast_modinfo($course);
print_object($info);
</code>

==Usage==
The cmid (course module id) is used widely throughout Moodle to identify a specific activity / resource. Some of the most important uses are:
* When linking to a modules 'view.php' script, it is passed as the 'id' parameter
* To get the 'context' for the module (used when checking user capabilities or linking files to an activity), via the function call 'context_module::instance($cmid)' (before Moodle 2.2 this was 'get_context_instance(CONTEXT_MODULE, $cmid)')
* Every log entry in 'mdl_log' that relates to a specific activity has the 'cmid' field set

==More documentation==
* [[Module visibility and display]]
* [http://phpdocs.moodle.org/HEAD/core/lib/course_modinfo.html course_modinfo PHPdocs]
* [http://phpdocs.moodle.org/HEAD/core/lib/cm_info.html cminfo PHPdocs]
* [https://moodle.org/mod/forum/discuss.php?d=255653#p1108750 mdl_course_modules table forum discussion]

Course module

2020-06-23T08:16:44Z

Libertymoodle: /* Add mdl_course_modules forum discussion link */

Talk:Moodle 3.8 release notes

2020-04-07T11:09:45Z

Libertymoodle: /* PHP v7.4 support */

==Server requirements==

Does Moodle 3.8 run under PHP version 7.4? MDL-66260 implies that full suport for PHP 7.4 is still under development. This doc should be specific about support for PHP 7.4.

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 11:08, 7 April 2020 (UTC)

Talk:Moodle 3.8 release notes

2020-04-07T11:09:00Z

Libertymoodle: /* PHPv7.4 support */

==Server requirements==

Does Moodle 3.8 run under PHP version 7.4? MDL-66260 implies that full suport for PHP 7.4 is still under development.
--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 11:08, 7 April 2020 (UTC)

Better handling of overdue quiz attempts

2019-04-04T08:16:57Z

Libertymoodle: /* See also links */

{{Infobox Project
|name = Handling of overdue quiz attempts
|state = Implementation complete. Testing.
|tracker = MDL-3030, MDL-4309
|discussion = [http://moodle.org/mod/forum/discuss.php?d=201355 Quiz forum thread about testing] [http://moodle.org/mod/forum/discuss.php?d=188534 Old Quiz forum thread about the proposal]
|assignee = [[User:Tim Hunt|Tim Hunt]]
}}
{{Moodle 2.3}}

There is a tricky issue to do with what happens exactly when time runs on on a quiz. On the one hand, we want to let students use every second of time. On the other hand, the end of a quiz is often a time of high server load, and so Moodle is likely to responding slowly. Therefore, we have to prevent students from cheating on the time-limit while still processing their last-minute submission even if the server is heavily loaded.

There is also the problem of what happens if the student just logs out and does not submit at all. At the moment the attempt goes into a sort of limbo where Moodle can't really do anything with it.

==What happens at the moment==

Currently there are only really two states a quiz attempt can be in, and they are distinguished by whether quiz_attempts.timefinish is 0 or contains a time-stamp.

[[Image:Quiz_attempt_states_now.png]]

At most one attempt is allowed to be in the '''In progress''' state at any time.

After time expires, (either because the time limit runs out, or the close date passes) the attempt is in a weird state. Well, not really, the attempt is still considered to be '''In progress''', but the student is no longer allowed to access it, so there is no way to get at the '''Submit all and finish''' button to submit it. Also, if the quiz allows more than one attempt, the student cannot start a new attempt, because they already have an '''In progress''' attempt (which they are not allowed to access!)

The known work-around is, as teacher, to:
# edit quiz settings to allow more time;
# login-as the student and submit the quiz;
# set the time-limit or close data back to what it should be.
This is a real pain.

Before reading on, you may wish to remind yourself of the [[Quiz user interface overview]], so you know what the key scripts view/startattempt/attempt/processattempt/summar/review.php each do.

To document the two existing transitions in some detail (note, all transitions are logged, I have not bothered to say that every time):

===Transition: Start attempt===

Goes to: In progress

Allowed when: If the student does not currently have any '''In progress''' attempt, and if they meet all the conditions imposed by the [[Quiz access rules|access rules]], they may start one.

How it is done: The student clicks the '''Start attempt''' button on view.php. Technically, this takes the form of a POST request to startattempt.php.

What happens:
# The attempt, and corresponding $quba, are created.
# They are initialised by adding all the questions, which may depend on randomisation, and 'each attempt builds on last'.
# The attempt and all associated data is written to the database.
# A quiz_attempt_started event is raised. (This even it not used in standard Moodle.)

===Transition: Submit all and finish===

Goes from: In progress

Goes to: Finished

Allowed when: The student has an '''In progress''' attempt, which they are currently allowed to access according to the access rules. In particular, where the time limit has not run out, and the close date has not passed.

How it is done: Either
* The student clicks the '''Submit all and finish''' button on summary.php; or
* Time runs out while the student is working on the quiz, and so the quiz is submitted automatically (if JavaScript is enabled).
Technically, this takes the form of a POST request to processattempt.php, althought the code that does the work is the quiz_attempt::finish_attempt method in attemptlib.php.

What happens:
# All questions that are not already finishes are finished.
# The updated question states are written to the database.
# The quiz_attempt record is updated with the timefinish and the total mark.
# The overall quiz grade (combining all the student's attempt scores) is updated, and stored in the gradebook.
# A quiz_attempt_submitted event is raised. (This is used by the quiz itself to send out any tutor or student notification messages that are enabled.)

==Rough outline of the solution==

We will introduce a new quiz settings '''When time expires''' and '''Grace period'''. When time expires is the strategy we will use for overdue attempts. For some strategies, they will need an amount of extra time that is the grace period. The possible strategies are:

# Submit attempt automatically,
# Allow a grace period to submit, but not change any responses, or
# That's it. Tough luck! - ''we need a better name for this!''

1. Corresponds to doing an automatic submit all and finish. 3. Corresponds to automatically moving the attempt to the '''Abandoned state'''. See below. 2. is more interesting (and is what the OU wants for assessed tests).

If the student has not submitted their attempt when time runs out, then the attempt moves into the '''Overdue''' state. In this state, when the student tries to get to the quiz attempt, then can only go to the Summary page, where all they can do is to click the '''Submit all and finish''' button.

If they finish submitted before the grace period runs out, then their attempt is counted.

If the student still does not submit, then the attempt moves into the '''Abandoned''' state. This means that the student is not prevented from starting a new attempt, if the quiz allows it.

''Question: should we allow the student to abandon the current attempt at any time? For example, if an interactive quiz allows multiple attempts, and the student has got off to a bad start, should we let them abandon and start again, or should we force them to '''Submit all and finish''' if they want a new attempt? - for now we will not allow students to abandon any attempt.''

In addition, we will start storing the quiz_attempt.state explicitly in the database, rather than relying on deducing it from timefinish or other columns. In a sense this is redundant information, but since significant things happen when the state changes (e.g. a message might be sent) I think making the state, and hence the state transition, explicit, will make the code clearer.

We will need code that detects when an attempt is in the 'wrong' state. For example, if a state is stored in the database as '''In progress''', but time has now expired, then we will need to detect that and correct it by triggering the correct state transition. I think we need to do this in two ways:
# Whenever we load an attempt from the database. This ensure that if the user is actively working on the quiz when a state transition is supposed to happen, they will immediately see the attempt change state.
# We will need to add a cron script that detects attempts becoming overdue when no-one is looking at them.
(Note there is a subtlety, the JavaScript timer that runs in the user's browser will try to automatically trigger a submit, they may be happening at the same time as a teacher is reviewing the attempt (which might trigger 1) and cron may also be running at the same time (which might trigger 2). Therefore, we need a clear protocol to avoid nasty race-conditions.

Actually, a possible third way (instead of, or in addition to cron). Perhaps we should detect this when the quiz settings (or overrides) are edited, and check all attempts then and trigger state transitions. This might be a performance problem on quizzes with thousands of attempts.

==New state diagram==

[[Image:Quiz_attempt_states.png]]

At most one attempt can be in either the '''In progress''' or '''Overdue''' states at any time.

The existing transitions need to be updated:
* They all need to set the new quiz_attempt.state column as part of What happens.
* The transition Submit all and finish can now also go from '''Overdue''' to '''Finished'''.
* When time runs out as a student is working on their quiz attempt, this should no longer trigger an automatic Submit all and finish. Instead it should trigger an automatic Time expires.

The new transitions are:

===Transition: Time expires===

Goes from: In progress

Goes to: Overdue

Allowed when: Time expires, either due to the time-limit, the close date, or some other custom access rule; or because the teacher has edited the time limit and/or close date and shortened them; and when the overdue strategy is "Allow a grace period to submit, but not change any responses".

How it is done: Detected automatically by the Moodle code, either because
* time has passed;
* the teacher has edited the quiz settings or overrides to shorten the time limit and/or close date; or
* triggered by the countdown timer JavaScript, in which case this will trigger a POST to processattempt.php.

What happens:
# quiz_attempt.state is updated
# quiz_attempt_overdue event is raised. (The quiz will use this itself to send a warning message to the student, if that is enabled.)
# If the student is currently working on the quiz, they are redirected to the summary.php page.

===Transition: Give up===

''(not sure that is the best name)''

Goes from: Overdue / In progress

Goes to: Abandoned

Allowed when: Time expires, and the overdue strategy is "That's it. Tough luck!"; or the grace period expires when an attempt is in the '''Overdue''' state.

How it is done: Detected automatically by the Moodle code, either because
* time has passed;
* the teacher has edited the quiz settings or overrides to shorten the time limit, close date and/or grace period; or
* triggered by the countdown timer JavaScript, in which case this will trigger a POST to processattempt.php; or
* if we decide to allow it, the student clicks a 'Give up button', perhaps on the summary page.

What happens:
# quiz_attempt.state is updated
# quiz_attempt_abandoned event is raised. (For completeness. I don't foresee a use for this at the moment.)

===Transition: Time limit extended===

''This shows the kind of tricky thing that can happen. We have to consider what happens if the teacher edits the quiz settings to extend the time limit when an attempt has already been marked overdue.''

Goes from: Overdue

Goes to: In progress

Allowed when: The teacher edits the quiz settings or the overrides and extends the time limit.

How it is done: Detected automatically by the Moodle code.

What happens:
# quiz_attempt.state is updated
# quiz_attempt_restarted event is raised. (For completeness. I don't foresee a use for this at the moment.)

==What can be accessed when==

For an '''In progress'''' attempt: The student can access attempt.php and summary.php; the teacher can access review.php.

For an '''Overdue'''' attempt: The student can access review.php and summary.php; the teacher can access review.php.

For a '''Finished'''' attempt: The student and teacher can access review.php.

For an '''Abandoned'''' attempt: The student and teacher can access review.php.

==Summary of changes==

===Database changes===

* New column quiz.overduehandling (char) to store which strategy we will use for overdue attempts.
* New column quiz.graceperiod (int) to store the time an attempt is allowed to remain in the '''Overdue''' state.
* New column quiz_attempt.state (char) to explicitly store the attempt state.

===New capability===

* mod/quiz:emailwarnoverdue to control overdue warning messages.

===UI changes===

* New fields 'When time expires' and 'Grace period' on the quiz settings form, with corresponding admin settings.
* Do we need even more columns of 'review options' on the quiz settings form? (For example for '''Overdue''' and '''Abandoned''' attempts.) Perhaps it is time to move these settings to a separate page?
* Information about the grace period may need to be displayed on the quiz settings page, or on the summary page for overdue attempts.
* List of attempts on the view.php page needs to indicate the state of attempts.
* review.php page needs to indicate the attempt state.
* Display attempt state in the quiz reports where appropriate.

==Rough work break-down==

# <span style="color:green">Done!</span> New quiz.overduehandling, quiz.graceperiod and quiz_attempt.state DB columns definition, upgrade code, backup & restore.
# <span style="color:green">Done!</span> Overdue handling and Grace period setting on quiz form, with any validation. Verify create / edit works.
# <span style="color:green">Done!</span> Implement back end of the three new transitions.
# <span style="color:green">Done!</span> Code where attempts are loaded to identify attempts in the wrong state and trigger a transition if necessary.
# <span style="color:green">Done!</span> Catch the quiz_attempt_overdue event and send an email.
# <span style="color:green">Done!</span> Make attempt_state clear on the view page list of past attempts.
# <span style="color:green">Done!</span> Update logic for the 'Start attempt button', and in startattempt.php so that for overdue attempts users are redirected to the summary page.
# <span style="color:green">Done!</span> Update summary page to display appropriate information about overdue attempts.
# <span style="color:green">Done!</span> Update processattempts.php so that it correctly handles one single submission after an attempt becomes overdue, and, for overdue attempts, will only redirect to the summary page.
# <span style="color:green">Done!</span> Display the attempt state on the review page.
# <span style="color:green">Done!</span> Add the attempt state to the overview and responses quiz reports (this will actually be a change in the base class).
# <span style="color:green">Done!</span> Add new options to the attempt and overview reports to filter the report by attempt state. (We can probably usefully refactor the settings forms and preferences handling to extract a base class.)
# <span style="color:red">Out of scope</span> While we are working here, we should really update these two reports to use the Moodle 2.x enrolment SQL, instead of get_users_by_capability.
# <span style="color:green">Done!</span> Change the statistics report to analyse attempts with state = finished, rather than timefinish <> 0.
# <span style="color:green">Done!</span> Cron to detect attempts in the wrong state and trigger state transitions.
# <span style="color:green">Done!</span> Review all remaining occurrences of ->timefinish in the quiz code.
# <span style="color:green">Done!</span> Check the quiz results block - no changes required.
# <span style="color:red">Out of scope</span> - the official work-around is: "Don't do that", at least for now - Deal with what happens when the teacher edits the quiz settings - which might change the times or the policies. Work out what to update.

== Test script==

The 3 examples at http://moodle.org/mod/forum/discuss.php?d=188534 are a good starting point. They just need to be elaborated.

==Hypothetical other transitions==

The following state-transitions can also be conceived, and could be implemented in the future, but they are out-of-scope for this proposal.

===Transition: Reopen attempt===

Goes from: Finished / Abandoned

Goes to: In progress

Allowed when: Time has not expired, and the current user has the appropriate capability.

(For example, the student accidentally clicked Submit all and finish, and the teacher wants to be nice and undo that for them. Alternatively an attempt has become Abandoned because time ran out, but then the teacher extended the grace period or time limit, and so wants to re-open some attempts. In this case, the transition may go to '''Overdue''', or perhaps that is a different transition, or perhaps the right way to handle that is to first transition to '''In progress''' and then transition to '''Overdue'''. I think it is clear why this is being considered out-of-scope.)

How it is done: Probably clicking a button on the review page or in the quiz reports. This would probably be a POST to a new reopenattempt.php

What happens: This is a bit tricky because lots of complex stuff happens on Submit all and finish that now needs to be undone, but I think a possible approach is to delete any question_attempts_steps added by the finish action (and any that follow them) and then use a regrade of the attempt to reset everything else.

Actually, it is much easier to re-open an '''Abandoned''' attempt than a '''Finished''' one. Perhaps we should consider them two different transitions, or perhaps reopening an '''Abandoned''' attempt can be treated the same as Time limit extended.

===Transition: Count this anyway===

Goes from: Abandoned

Goes to: Submitted

Allowed when: The current user has the appropriate capability.

(For example a teacher decides that even though the student abandoned their attempt, it should be counted anyway.)

How it is done: Probably clicking a button on the review page or in the quiz reports. This would probably be a POST either to processattempt.php with extra arguments, or to a new script.

What happens: Probably very similar to Submit all and finish.

==See also==

* MDL-3030 Late quiz attempts should be closed automatically
* MDL-4309 Ability for late quizzes (with penalty)
* MDL-35322 Student didn't submit quiz, status is Never Submitted, version 2.3.1
* [[Quiz]] developer documentation
* Draft user documentation: [[Quiz time controls on attempts]]

States of a quiz attempt

2019-04-04T08:11:34Z

Libertymoodle: /* Relevant tracker issues */

{{obsolete}}
See [[Better handling of overdue quiz attempts]] for more current information.

This page relates to the problem of the following scenario:
# Student starts an attempt at a timed quiz.
# Student logs out and goes away.
# Quiz time limit expires.
# Student (or teacher) comes back. They now cannot continue (or review, or complete) the quiz attempt. They are stuck.
::That's not what actually happens. Actually on 4 student see a button to continue his attempt. He press it and goes to the attempt, which is instantly submitted, and he get returned to quiz intro. He could then start a new attempt ... if there is no time delay between attempts. If there is he is stuck.--[[User:Oleg Sychev|Oleg Sychev]] 19:55, 24 November 2009 (UTC)

Different people have different desires for how this is handled. The aim of this page is to collect together all the things that different people might want, so we can try to design a solution that makes everyone happy.

Currently this page is just a random dump of things Tim remembered, please feel free to add to, or edit it.

==What currently happens==

===The states a quiz attempt can be in===

* {before the attempt is started}. Not sure if this really exists. Before the attempt has been started, it does not exist!
* During the quiz attempt (Quiz attempt open). This is distinguished by $attempt->timefinish being 0.
* After the attempt is finished. This is distinguished by $attempt->timefinish being non-zero.

===Behaviour===

* A user can have at most one quiz attempt open at any time.
* If the user is attempting the quiz when the time expires, and if they have JavaScript on, then the quiz is automatically submitted for them.
* If the student is not attempting the quiz when the time expires, then their attempt is not submitted, and neither the student nor the teacher can submit it.
Actually the attempt will be graded 0, but individual questions may be regraded if page was saved.
Teachers could use it to calculate attempt grade manually, but they really don't like it.--[[User:Oleg Sychev|Oleg Sychev]] 19:55, 24 November 2009 (UTC)
* Time can expire either because of $quiz->timelimit, or $quiz->timeclose.
* There is a capability mod/quiz:ingoretimelimit for accessibility reasons. This causes $quiz->timelimit, but not $quiz->timeclose, to be ignored.
* After the attempt is submitted, students may, or may not be able to review, depending on the quiz review settings and whether $quiz->timeclose has passed.
* In addition to the only one open attempt rule, there may also be a delay between the end of one quiz attempt and the start of the next ($quiz->delay1/2).

==What we would like to happen==

===The states we need to distinguish===

* {before the attempt is started}
* Quiz attempt open, time has not expired.
* Quiz attempt open, time has expired.
* Quiz attempt submitted, some questions need manual grading.
* Quiz attempt submitted, all questions graded.
Actually these states makes quiz time delay more complicated.
The question is what state it should use as an end of previous attempt?
It should be submission for quizzes without time limit.
But for quizzes with time limit it should be min(time expiration, submission) otherwise we still may get
problem with time delay mentioned above.--[[User:Oleg Sychev|Oleg Sychev]] 19:55, 24 November 2009 (UTC)

Might we also want/need to distinguish the states 'results not visible yet', and 'results released to student', for a submitted quiz. These two are orthogonal to whether any questions need manual grading, so that actually leads to four sub-states under submitted.

===Behaviour===

* Teacher should have the option to submit an attempt when the student forgot.
* Student should have the option to submit an attempt late (but not answer any more questions) when they forgot. Probably the best way to do this is that after time has expired, if the student is still allowed to Submit all and finish, they can only go to the attempt summary page (in Moodle 2.0) and click the submit button.
* Some people like the current behaviour: the student must submit on time, and if they don't they don't get a grade, and it is tough luck. Therefore, if students are allowed to submit the quiz late, there should be a time limit for how much extra time they have in which to do so (which can be anything from 0 to infinity).
* There should be an option which, at the moment when time expires on an attempt, send an email to the student reminding them that they have not submitted it, and explaining to them how to do so, and how long in which they have to do so.
* Alternatively, the quiz may have an option set to automatically submit any quiz attempt the moment time has expired.
* May want an option where, if the student is allowed to submit late, we do process any updated answers, but a penalty is applied to their score.
* May want an option for a teacher to un-submit a quiz attempt, for those situations where a student has (claims to have) clicked Submit all and Finish too early, by mistake.
* Teachers can delete any quiz attempt (open or submitted) at any time (''this has been implemented for a long time'')
* Giving teacher the ability to decide, that particular student in particular attempt could bypass time delay (without deleting previous attempt) will resolve a great deal of the problems. (''this is implemented in Moodle 2.0'')

===Other ideas===

* Some people may want to count un-submitted attempts if quiz has a limit on a number of attempts, other may want to exclude them.

'' This is not really possible, given the assumption the quiz has that there is at most one open attempt, which can either be submitted or deleted, and once it is submitted, it counts. I also don't really see the point of this. If you are being that flexible, why have a limit on the number of attempts at all? ''

* May want an option for a teacher to extend time limit for particular attempt (if, for example, computer hangs during the attempt, or the student press submit near the finish and wait more than 60 seconds)

'' This is, as opposed to extending it for all attempts for a particular student. This would be a lot of work to implement, and only occasionally useful. For now, I think it is sufficient to have the option to change the time limit for one student. You can always extend it until they have submitted that one attempt, and then change it back. ''

* (I don't know whether it really possible, but it's a very good option to have) Save current attempt state with responses in a browser window if submitting request on server failed. Sometimes server go down during important attempts (exams and so no), that's quite bad for timed quizzes. At least we could send AJAX request to the server before submitting to verify it still working (should work in couple with teacher-defined time limit extension mentioned above to prevent abuse).

'' This is not possible. ''

* ... please add more ideas here ...

===Changes to the code===

''Note that this builds on top of Moodle 2.0. If you don't know what things like the summary page are, or how the quiz reports work in the latest version, this may not make any sense.''

* New capability mod/quiz:submitlateattempt - can apply to students, and/or teachers, but with slightly different meaning. (Teacher here is probably defined by mod/quiz:grade, or mod/quiz:viewreports. Or perhaps it is clearly to have separate capabilities mod/quiz:submitmylateattempt and mod/quiz:submitanylateattempt.) Or perhaps rather than a capability, a quiz setting saying how much extra time students have after their attempt becomes overdue, to go in and submit it.

* If a student has mod/quiz:submitlateattempt, and/or if they are still within the extra time allowed, then they can get at overdue quiz attempts, but they can only go to the summary page in order to click the Submit all and finish button.

* For teachers with mod/quiz:submitlateattempt, there will be a new button in the quiz reports (next to delete attempts and regrade attempts) to submit any overdue quiz attempts that have been selected using the check-boxes.

* New database column quiz_attempt.state, to make the current state of each attempt clear. (Not sure if this is really necessary.)

* Code on cron, or when the attempt is accessed, to update the attempt state if, for example, time has expired since it was last changed.

* A quiz option, and code on cron, to automatically submit overdue quiz attempts if that is what the teacher wants.

* A quiz option, and code on cron, to email a student when an attempt becomes overdue, telling them how long the still have to submit it, and how to do so.

* Possibly new column quiz_attempt.finishedby, to record the userid of the user who submitted the attempt, so we know if the teacher has submitted a later attempt for the student. Could be NULL, if late attempts are submitted automatically.

* Code in the question engine to correctly process incomplete attempts when an overdue attempt is submitted.

==See also==

===Discussion===

* Please discuss this in [http://moodle.org/mod/forum/discuss.php?d=138660 this Quiz forum thread].

===Relevant tracker issues===

* MDL-3030 Late quiz attempts should be closed automatically
* MDL-3452 Use saved answers when marking late submissions
* MDL-4309 Ability for late quizzes (with penalty)
* MDL-20956 Student can't start new attempt if a quiz has timle limit between attempts and time limit for a quiz, and he doesn't submit previous attempt closing browser window instead
* MDL-35322 Student didn't submit quiz, status is Never Submitted, version 2.3.1
* ... please add other relevant tracker issues here.

===See also===

* [[Better handling of overdue quiz attempts]]
* [[Goals_of_an_online_assessment_system|Goals of an online assessment system]]
* [http://moodle.org/mod/forum/discuss.php?d=118343 Closing unfinished attempts - possible solution for 1.9]
* [https://docs.moodle.org/23/en/User_talk:John_Rich Moodle Documents]

[[Category:Quiz]]

Custom fields API

2019-04-03T11:44:04Z

Libertymoodle: /* Add See also */

{{Moodle 3.7}}

== Custom fields API overview ==

Custom fields API was added in Moodle 3.7. It allows to configure custom fields that can be added to various contexts. Each '''component''' (or plugin) that wants to use custom fields can define several '''areas'''. For example, 'core_course' component defines an area 'course' that allows to add custom fields to the courses, the same component can define another area 'coursecat' that will allow to add custom fields to the course categories. Inside each area the component/plugin can decide whether to use or not to use '''itemid'''. For example, course custom fields are the same throughout the system and they don't use itemid (it is always 0). But there could be an activity module that would want to configure different custom fields for each individual instance of module, then this module would use the module id as the itemid, as in ([https://github.com/marinaglancy/moodle-mod_surveybuilder example]). This would allow to create modules similar to mod_data and mod_feedback where each instance has it's own set of fields.

New plugin type "customfield" was also added as part of the Custom fields API. Additional types of custom fields can be installed into /customfield/field/ .

== How to use custom fields ==

Component/plugin that uses custom fields must define a '''handler class''' for each area and a '''configuration page'''. Handler class must be called '''<PLUGINNAME>/customfield/<AREA>_handler''' and be placed in autoloaded location (<PLUGINDIR>/classes/customfield/<AREA>_handler.php . This class must extend '''\core_customfield\handler''' . Configuration page may be located anywhere. For course custom fields configuration the admin settings page is used [https://github.com/moodle/moodle/blob/master/course/customfield.php /course/customfield.php]. If the area uses itemid this page should take itemid as a parameter.

Handler has protected constructor, to get a handler call create() method. Some areas may choose to return a singleton here:

<code php>
$handler = HANDLERCLASS::create($itemid);
</code>

Configuration page contents will be:

<code php>
$output = $PAGE->get_renderer('core_customfield');
$outputpage = new \core_customfield\output\management($handler);
echo $output->render($outputpage);
</code>

Handler must implement all abstract methods (calculate configuration or instance context, check permissions to configure, view or edit) and also may choose to overwrite:
<code php>
handler::uses_categories()
handler::generate_category_name()
handler::config_form_definition() // For example, the course_handler adds "locked" and "visibility" settings that control who can edit or view the particular field.
handler::setup_edit_page() // Sets page context/url/breadcrumb for the customfield/edit.php page, in some cases it must be overridden.
</code>

=== Add custom fields to the instance edit form ===

Custom fields are added to the '''instances'''. For example, course custom fields are added to the courses, so courseid is the instanceid. In the example of [https://github.com/marinaglancy/moodle-mod_surveybuilder mod_surveybuilder] we use $USER->id as the instanceid (which means that in this example one user can fill the survey in one module only once). In each case of using custom fields there should be a clear concept of an '''instance'''. Instanceid is required to save the data but it may be empty when we render the instance edit form (for example, the course is not yet created).

Developer must add custom fields callbacks to the instance edit form. If the instance is "made up" (like in mod_surveybuilder), a new form has to be created with 'id' field in it that will refer to the instanceid.

The following callbacks should be used in form definition, definition_after_data, validation and after form submission:
<code php>
$hander->instance_form_definition()
$hander->instance_form_before_set_data()
$hander->instance_form_definition_after_data()
$hander->instance_form_validation()
$hander->instance_form_save()
</code>

On deletion of an instance or on deletion of the whole item call:
<code php>
$hander->delete_instance()
$hander->delete_all()
</code>

=== Retrieving instances custom fields ===

How custom fields are used depends entirely on the situation. The following handler methods will help you to retrieve custom fields values for the given instance(s):

<code php>
$handler->export_instance_data()
$handler->export_instance_data_object()
$handler->display_custom_fields_data()
</code>

Additional methods for advanced usage:
<code php>
$handler->get_instance_data()
$handler->get_instances_data()
$handler->get_instance_data_for_backup()
</code>
Method restore_instance_data_from_backup() exists in the handler class but not implemented

To retrieve the list of custom fields used in the given component/area/itemid you can use:
<code php>
$handler->get_categories_with_fields()
$handler->get_fields()
</code>
List of fields is cached in the handler and these two functions can be called multiple times.

=== Privacy API ===

Custom fields API does not export or delete any data because it does not know how custom fields are used, what data is considered user data and if it is considered private or shared data.

Plugins that store user information in custom fields should link subsystem in their get_metadata:
<code php>
$collection->link_subsystem('core_customfield', 'privacy:metadata:customfieldpurpose');
</code>

And they can use the following methods in the export/delete functions:
<code php>
use core_customfield\privacy\provider as customfield_provider;

customfield_provider::get_customfields_data_contexts()
customfield_provider::export_customfields_data()
customfield_provider::delete_customfields_data()
customfield_provider::delete_customfields_data_for_context()
</code>

In case when custom fields configuration is considered to be user data (configuration means the definition of the fields, not the instance data), there are also couple of methods to help with privacy API implementations:
<code php>
customfield_provider::get_customfields_configuration_contexts()
customfield_provider::delete_customfields_configuration()
customfield_provider::delete_customfields_configuration_for_context()
</code>
Export of configuration was not yet implemented at the time of writing this because of difficult implementation and very unclear use case. If it is needed please feel free to contribute to Moodle.

== Custom fields plugins ==

Custom fields plugin type was added to allow implement different types of custom fields (somehow similar to user profile fields plugin type). Plugins are located in '''/customfield/field/''' and the full frankenstyle name of the plugins start with '''customfield_'''

Except for common [[Plugin files]] and tests the following classes must be present in customfield plugins (in respective autoloaded locations):
<code php>
namespace customfield_<PLUGINNAME>;
class field_controller extends \core_customfield\field_controller;
class data_controller extends \core_customfield\data_controller;

namespace customfield_<PLUGINNAME>\privacy;
class provider implements \core_privacy\local\metadata\null_provider, \core_customfield\privacy\customfield_provider;
</code>

== See also ==

MDL-64626 - Custom fields API (Moodle 3.7+) implementations and improvements

MDL-57898 - Add custom field types plugin and course custom fields functionality

Developer meeting January 2019

2019-01-09T07:17:03Z

Libertymoodle: /* Add custom reporting */

[[Developer meetings]] > January 2019 meeting notes

{| class="nicetable"
|-
| Time
| 13:00 UTC on Thursday, 10 January 2019
|-
| Join URL:
| https://moodle.zoom.us/j/259887936
|-
| Meeting recording (including searchable, indexed transcript and chat log)
| TBD
|-
| Meeting Minutes
| https://etherpad.net/p/MoodleDevCommunity-01-19
|-
| Discussion
| [https://moodle.org/mod/forum/discuss.php?d=378355 Discussion thread at moodle.org]
|}

== Proposed Agenda ==

'''This is an editable page. Please propose items you would like to present on (or request) here!'''

* Custom reporting in Moodle - is there any progress?
# Are there any plans to upgrade the Configurable Reports plugin? An official comment from Moodle or Juan would help calm the nerves.
# Status of the MUA customizable report builder proposal?

== Minutes ==

Minutes will be captured via Etherpad at https://etherpad.net/p/MoodleDevCommunity-01-19.
----
Please feel encouraged to raise topics you would like to present / discuss during these meetings. Contact [https://moodle.org/user/profile.php?id=1413178 Elizabeth Dalton] for details.

Developer meeting January 2019

2019-01-09T07:14:06Z

Libertymoodle: /* Add custom reporting */

[[Developer meetings]] > January 2019 meeting notes

{| class="nicetable"
|-
| Time
| 13:00 UTC on Thursday, 10 January 2019
|-
| Join URL:
| https://moodle.zoom.us/j/259887936
|-
| Meeting recording (including searchable, indexed transcript and chat log)
| TBD
|-
| Meeting Minutes
| https://etherpad.net/p/MoodleDevCommunity-01-19
|-
| Discussion
| [https://moodle.org/mod/forum/discuss.php?d=378355 Discussion thread at moodle.org]
|}

== Proposed Agenda ==

'''This is an editable page. Please propose items you would like to present on (or request) here!'''

* Custom reporting in Moodle - is there any progress?
# Are there any plans to upgrade the Configurable Reports plugin?
# Status of the MUA customizable report builder proposal?

== Minutes ==

Minutes will be captured via Etherpad at https://etherpad.net/p/MoodleDevCommunity-01-19.
----
Please feel encouraged to raise topics you would like to present / discuss during these meetings. Contact [https://moodle.org/user/profile.php?id=1413178 Elizabeth Dalton] for details.

AJAX

2019-01-03T11:01:56Z

Libertymoodle: /* Links */

'''AJAX (Asynchronous Javascript and XML)''' is a modern web design technique that allows for more interactivity by making webpages that fetch data in the background and alter themselves without reloading the entire page. This helps to make a page feel much more like an application than a web page. AJAX is a new way of working with existing technologies (including HTML, [[Javascript]], [[CSS]] and the ''XMLHttpRequest object'' amongst others) rather than a new piece of technology in itself.

Although AJAX indicates that XML is used, the term really relates to the group of technologies and in Moodle we tend to favour use of JSON rather than XML as the syntax is lighter and leads to a smaller output. It is also easier to construct from php data structures.

== Ajax in Moodle ==
{{ Moodle 2.9 }}

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions.

Some benefits of this system are:
# No new ajax scripts need auditing for security vulnerabilities
# Multiple requests can be chained in a single http request
# Strict type checking for all parameters and return types
# New webservice functions benefit Ajax interfaces and web service clients

So the steps required to create an ajax interaction are:

# Write or find an existing web service function to handle the ajax interaction: See [[ Web_services ]]
# White list the web service for ajax. To do this, you can define 'ajax' => true in your function's definition, in db/services.php. Only functions that are whitelisted using this mechanism will be available to the ajax script.
# Call the web service from javascript in response to a user action:

Example calling core_get_string:
<code javascript>
require(['core/ajax'], function(ajax) {
var promises = ajax.call([
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'pluginname' } },
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'changerate' } }
]);

promises[0].done(function(response) {
console.log('mod_wiki/pluginname is' + response);
}).fail(function(ex) {
// do something with the exception
});

promises[1].done(function(response) {
console.log('mod_wiki/changerate is' + response);
}).fail(function(ex) {
// do something with the exception
});
});
</code>

Note: This example chains two separate calls to the 'core_get_string' webservice in one http request

Note: Don't actually fetch strings like this, it is just an example, use the 'core/str' module instead.

If there is only a single action, a simpler form is possible (example from Assignment):

<code>
ajax.call([{
methodname: 'mod_assign_submit_grading_form',
args: {assignmentid: assignmentid, userid: this._lastUserId, jsonformdata: JSON.stringify(data)},
done: this._handleFormSubmissionResponse.bind(this, data, nextUserId),
fail: notification.exception
}]);
</code>

('notifcation' comes from the 'core/notification' javascript module and provides a useful popup error message if the call fails)

To update parts of the UI in response to Ajax changes, consider using [[ Templates ]]

For information on writing AJAX scripts for Moodle before Moodle 2.9 see: [[ AJAX pre 2.9 ]]

Watch a video about using templates with webservices and AJAX in Moodle: https://www.youtube.com/watch?v=UTePjRZqAg8

Tricky things to know about using webservices with ajax calls:
# Any call to $PAGE->get_renderer() requires the correct theme be set. If this is done in a webservice - it is likely that the theme needs to be a parameter to the webservice.
# Text returned from a webservice must be properly filtered. This means it must go through external_format_text or external_format_string (since 3.0 - see MDL-51213) with the correct context.
# The correct context for 2 is the most specific context relating to the thing being output e.g. for a user's profile desciption the context is the user context.
# After adding any dynamic content to a page, Moodle's filters need to be notified via M.core.event.FILTER_CONTENT_UPDATED (MDL-51222 makes this easier)
# After adding or changing any webservice definition in db/services.php - you must bump the version number for either the plugin or Moodle and run the upgrade. This will install the webservice in the DB tables so it can be found by ajax.

In some very rare cases - you can mark webservices as safe to call without a session. These should only be used for webservices that return 100% public information and do not consume many resources. A current example is core_get_string. To mark a webservice as safe to call without a session you need to do 2 things.
# Add 'loginrequired' => false to the service definition in db/services.php
# Pass "false" as the 3rd argument to the ajax "call" method when calling the webservice.
The benefit to marking these safe webservice is that (a) they can be called from the login page before we have a session and (b) they will perform faster because they will bypass moodles session code when responding to the webservice call.

== See also ==

* [[ AJAX pre 2.9 ]]
* [[Templates]]
* [[Javascript Modules]]
* [[Javascript FAQ]]
* [[Javascript]]
* [[Firebug#Debugging_AJAX_with_Firebug|Debugging AJAX with Firebug]]

* [https://adaptivepath.org/ideas/ajax-new-approach-web-applications ''Ajax: A New Approach to Web Applications'', the original Ajax article by Adaptive Path] (This article is also preserved on the [https://web.archive.org/web/20070225140912/http://www.adaptivepath.com/publications/essays/archives/000385.php Internet Archive])
* [http://developer.mozilla.org/en/docs/AJAX:Getting_Started ''AJAX: Getting Started'' article on developer.mozilla.org]
* [http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html ''10 places you must use AJAX'' by Adam Bosworth] (This link is now dead, but the article is preserved on the [https://web.archive.org/web/20060127015713/http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html Internet Archive copy])
* [http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype ''Considering Ajax, Part 1: Cut through the hype'' from IBM developerworks] (Also a dead link... [https://web.archive.org/web/20080602101238/http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype Internet Archive copy])
* [http://en.wikipedia.org/wiki/Ajax_%28programming%29 Wikipedia article on ''AJAX'']
* [http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ How to Make Your AJAX Applications Accessible: 40 Tutorials and Articles] (Also a dead link... [https://web.archive.org/web/20090225094656/http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ Internet Archive copy])
*[http://www.ajaxload.info/ AJAX loading icon generator]

[[Category:Javascript]]
[[Category:AJAX]]

Talk:Moodle and PHP

2018-12-18T08:24:21Z

Libertymoodle: /* memcached on Windows */

Does anybody know whether as of today neither MSSQL nor SQLSRV are still available under php7 ? [[User:German Valero|German Valero]] ([[User talk:German Valero|talk]])
: Hi German, 99.99% sure mssql won't be ever back, after a voting it [http://php.net/manual/en/intro.mssql.php was removed] from php. And, last time I looked for [https://github.com/Azure/msphpsql/tree/PHP-7.0 sqlsrv] it was not ready yet. Maybe worth updating [[Moodle and PHP7#Can_I_use_PHP7_yet.3F|the "can I use it"]] section. --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] ([[User talk:Eloy Lafuente (stronk7)|talk]])

Is it good or bad to use PHP7 when installing an Ubuntu server (either local for testing or a production server) ?

Shall we change [https://docs.moodle.org/31/en/Step-by-step_Installation_Guide_for_Ubuntu#Why_we_prefer_.28or_don.27t_prefer.29_Ubuntu_16.04_over_Ubuntu_14.04 https://docs.moodle.org/31/en/Step-by-step_Installation_Guide_for_Ubuntu#Why_we_prefer_.28or_don.27t_prefer.29_Ubuntu_16.04_over_Ubuntu_14.04]

What are the options for running Memcached on Windows Server hosted Moodle sites? Yes? No? Do it? Don't do it?
--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 08:24, 18 December 2018 (UTC)

Moodle 3.5 release notes

2018-09-04T09:58:05Z

Libertymoodle: /* Added 3.5.1 release notes */

[[Releases]] > {{FULLPAGENAME}}

Release date: 17 May 2018

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.5%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.5].

See our [https://docs.moodle.org/35/en/New_features New Features page] for a more user-friendly introduction to Moodle 3.5 with screenshots.

If you are upgrading from previous version, make sure you read the [https://docs.moodle.org/35/en/Upgrading Upgrading] documentation.

==Server requirements==

These are just the minimum supported versions. We recommend keeping all of your software and operating systems up-to-date.

* Moodle upgrade: Moodle 3.1 or later
* PHP version: minimum PHP 7.0.0 ''Note: minimum PHP version has increased since Moodle 3.3''. PHP 7.1.x and 7.2.x are supported too. PHP 7.x could have some [https://docs.moodle.org/dev/Moodle_and_PHP7#Can_I_use_PHP7_yet.3F engine limitations].
* PHP extension '''intl''' is required since Moodle 3.4 (it was recommended in 2.0 onwards)
* (Recommendation only) If you use MySQL or MariaDB, make sure your database supports full UTF-8 (utf8mb4) if you install a new instance of Moodle. CLI script may be used to convert to utf8mb4 if you're upgrading. You may choose to keep using 'utf8_*', but then a warning will show that the database isn't using full UTF-8 support and suggest moving to 'utf8mb4_unicode_ci'. See [[:en:MySQL full unicode support|MySQL full unicode support]] for details. If you do enable utf8mb4 you *must* use the Barracuda file format.

=== Database requirements ===

Moodle supports the following database servers. Again, version numbers are just the minimum supported version. We recommend running the latest stable version of any software.

{| class="nicetable"
|-
! Database
! Minimum version
! Recommended
|-
| [http://www.postgresql.org/ PostgreSQL]
| 9.3
| Latest
|-
| [http://www.mysql.com/ MySQL]
| 5.5.31
| Latest
|-
| [https://mariadb.org/ MariaDB]
| 5.5.31
| Latest
|-
| [http://www.microsoft.com/en-us/server-cloud/products/sql-server/ Microsoft SQL Server]
| 2008
| Latest
|-
| [http://www.oracle.com/us/products/database/overview/index.html Oracle Database]
| 10.2
| Latest
|}

==Client requirements==

=== Browser support ===
Moodle is compatible with any standards compliant web browser. We regularly test Moodle with the following browsers:

Desktop:
* Chrome
* Firefox
* Safari
* Edge
* Internet Explorer

Mobile:
* MobileSafari
* Google Chrome

For the best experience and optimum security, we recommend that you keep your browser up to date. https://whatbrowser.org

Note: Legacy browsers with known compatibility issues with Moodle 3.5:
* Internet Explorer 10 and below
* Safari 7 and below

==Major features==

===GDPR===
* '''MDL-61275 - GDPR Consenting of Minors and Managing, Versioning and Tracking Privacy Policies and User Consents'''
* MDL-61292 - A new admin tool to manage policy documents
* MDL-61423 - Add age and location verification to identify minors
* MDL-61302 - Workflow to allow users to agree to all policies
* MDL-61301 - Report of user agreed policies and their versions
* MDL-61705 - Bulk accept of policies on behalf of users
* MDL-61864 - Include policy tool in core
* MDL-62286 - Add policy link to the site footer

* '''MDL-61306 - GDPR Data Requests and Data Registry'''
* MDL-59718 - A process to send a request to the data protection officer
* MDL-59720 - Delete personal data when it is no longer required
* MDL-61307 - Create a new privacy subsystem
* MDL-61362 - Ability to create data categories and purposes
* MDL-61486 - Data registry with purpose and retention period
* MDL-61489 - Report of plugin/components implementing the Privacy API
* MDL-61499 - Ability to set default purpose and retention periods for context levels
* MDL-61785 - Ability to review and confirm which expired data can be deleted
* MDL-61899 - Include data privacy tool in core
* MDL-61935 - Ability to specify the lawful bases for the collection of personal data

===Question bank tagging improvements===
* MDL-61066 - Expanded tagging functionality for question bank
* MDL-61133 - New modal to add/edit/remove tags on questions
* MDL-61135 - Filter questions by tag
* MDL-61138 - Show the list of questions in the 'Add a random question' dialog
* MDL-61363 - Ability to add question tags at a course level in the edit question form
* MDL-61364 - Manage tags at a question and course context level
* MDL-61380 - Allow filtering/adding random questions by tag for quizzes
* MDL-61410 - Add import/export support for course level question tags
* MDL-61444 - New capabilities for tagging questions

===UX: Usability improvements===
* MDL-62021 - Boost 4.0 Migration
* MDL-56511 - Update bootstrap 4 to final release
* MDL-61657 - Add images to the course cards on the dashboard

===LTI Advantage support===
* MDL-60416 - Add support for LTI Advantage 1.1

===RecordRTC for Atto===
* MDL-60848 - Implement RecordRTC Atto plugin as core feature
* MDL-61973 - Update RecordRTC Atto plugin buttons

===Messaging database tables===
* MDL-61254 - Merge messaging database tables
* MDL-36941 - Create new tables for messaging
* MDL-61255 - Ad-hoc task to upgrade messages to merged table

==Other Highlights==

===Global search===
* MDL-58885 - Add group support
* MDL-59434 - Content aware searching / alternate results sort orders
* MDL-60981 - Reindex a single area
* MDL-61028 - Allow filtering search by user
* MDL-61256 - Search of section titles, summaries

===Functional changes===
* MDL-2051 - Inform student whether and how their selected choice will display
* MDL-32585 - SCORM: option to force new attempts
* MDL-53226 - Add Moodle DB search engine
* MDL-55491 - Use cohort as badge criteria
* MDL-56246 - Add site wide default for grade export: include feedback
* MDL-59875 - Allow badges as criteria for other badges
* MDL-60119 - Feedback - Multiple choice (rated) - remove weights from answer
* MDL-61203 - Allow uploading of profile picture to be used as badge criteria
* MDL-61601 - Allow cohort themes
* MDL-61651 - LTI: line item definition within link to return gradable LTI links
* MDL-60811 - Bulk delete self-registered enrolments on participants page
* MDL-60682 - Ability to set date/time to nearest minute
* MDL-60441 - Ability to add a link to glossary entries
* MDL-58411 - Ability to apply file type restrictions for essay question type
* MDL-56945 - Add easy return path from PDF grading screen to list of submissions
* MDL-52811 - Add force language capability to course settings
* MDL-41090 - Allow teachers to embed files when manually grading questions

===Security issues===

* [https://moodle.org/mod/forum/discuss.php?d=371199 MSA-18-0007] Calculated question type allows remote code execution by Question authors
* [https://moodle.org/mod/forum/discuss.php?d=371200 MSA-18-0008] Users can download any file via portfolio assignment caller class
* [https://moodle.org/mod/forum/discuss.php?d=371201 MSA-18-0009] Portfolio forum caller class allows a user to download any file
* [https://moodle.org/mod/forum/discuss.php?d=371202 MSA-18-0010] User can shift a block from Dashboard to any page
* [https://moodle.org/mod/forum/discuss.php?d=371203 MSA-18-0011] User who did not agree to the site policies can see the site homepage as if they had full site access
* [https://moodle.org/mod/forum/discuss.php?d=371204 MSA-18-0012] Portfolio script allows instantiation of class chosen by user

===For developers===

* MDL-61307 - All plugins must implement [https://docs.moodle.org/dev/Privacy_API Privacy API] to be compliant with GDPR requirements. They must implement the API to report on, export and delete stored user data
* MDL-56511 - Bootstrap is upgraded to final release of version 4
* MDL-61869 - Infer rendering of templatables with no render method
* MDL-61298 - Boost: use navigation node icon

==== Upgrading plugins ====

'''1. Check for changes in core APIs'''

Read lib/upgrade.txt to check for the deprecations and core API changes, make sure you applied them to your plugin. Note that entries there are not sorted by priority but rather by integration time. Below is the list of upgrade.txt files that contain information about upgrading from Moodle 3.4 to Moodle 3.5 (note that if you upgrade from earlier versions there may be more files):

* [https://raw.githubusercontent.com/moodle/moodle/master/lib/upgrade.txt lib/upgrade.txt] changes to various core APIs, deprecations, functions removal
* [https://raw.githubusercontent.com/moodle/moodle/master/calendar/upgrade.txt calendar/upgrade.txt] changes to Calendar API
* [https://raw.githubusercontent.com/moodle/moodle/master/search/upgrade.txt search/upgrade.txt] changes to Global search API
* [https://raw.githubusercontent.com/moodle/moodle/master/message/upgrade.txt message/upgrade.txt] changes to Messages API
* [https://raw.githubusercontent.com/moodle/moodle/master/course/upgrade.txt course/upgrade.txt] changes to Course API

'''2. Check for changes in the API of your plugin type'''

Below is the list of plugin types that had API changes between Moodle 3.4 and 3.5:

* [https://raw.githubusercontent.com/moodle/moodle/master/enrol/upgrade.txt enrol/upgrade.txt] Enrolment method plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/mod/upgrade.txt mod/upgrade.txt] Activity module plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/auth/upgrade.txt auth/upgrade.txt] Authentication plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/course/format/upgrade.txt course/format/upgrade.txt] Course format plugins
* [https://raw.githubusercontent.com/moodle/moodle/master/question/type/upgrade.txt question/type/upgrade.txt] Question type plugins

'''3. Check for changes in the depended plugins'''

If your plugin depends on another plugin or calls methods from another plugin, read upgrade.txt in this plugin directory (if it exists). Below is the list of standard plugins that had changes between Moodle 3.4 and 3.5:

[https://raw.githubusercontent.com/moodle/moodle/master/admin/tool/mobile/upgrade.txt tool_mobile],
[https://raw.githubusercontent.com/moodle/moodle/master/admin/tool/usertours/upgrade.txt tool_usertours],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/assign/upgrade.txt mod_assign],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/feedback/upgrade.txt mod_feedback],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/quiz/upgrade.txt mod_quiz],
[https://raw.githubusercontent.com/moodle/moodle/master/mod/scorm/upgrade.txt mod_scorm],
[https://raw.githubusercontent.com/moodle/moodle/master/theme/boost/upgrade.txt theme_boost]

'''4. Do a smoke test of your plugin with developer debugging mode'''

Make sure to check on both Boost and Clean themes. Bootstrap was upgraded in Moodle 3.5

'''5. Run all behat and phpunit tests'''

==See also==
*[[Moodle 3.4 release notes]]
*[[Moodle 3.5.1 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.5]]

[[fr:Notes de mise à jour de Moodle 3.5]]
[[es:Notas de Moodle 3.5]]

NEWMODULE Adding capabilities

2018-04-25T13:38:21Z

Libertymoodle: /* archetypes */

{{New_Module}}
In order to add a capabilities for your <<NEWMODULE>> you need to:

==1. Create a file access.php in the <<NEWMODULE>>/db directory==

This should contain a list of the capabilities that you want to define. For example:

<code php>
$capabilities = array(
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
)
),

// Add more capabilities here ...
)
</code>

The various parts of the capability definition are:

===Capability name ('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>)===

This is the internal name used for this this capability. In addition to this internal name, you should also add the language string <<NEWMODULE>>:<<CAPABILITYNAME>> to your module's language file, to give the capability a name that users will see in the interface.

===riskbitmask===

Allowing people to do various things sometimes requires introducing possible security risks. For example, if you can post to a forum, you can post unsolicited advertising. To a certain extent users have to be trusted. To help administrators and teachers know what the issues are, each capability should list any associated risks. See [[Hardening_new_Roles_system]]. will be reflected in the list of icons of each row of the 'Override permissions'->roles page.

Technically, this value is a bit field, so you should combine the relevant risks constants with the '|' operator. So typical values might be:
* RISK_SPAM
* RISK_PERSONAL | RISK_XSS | RISK_DATALOSS

===captype===

Should be either 'read' or 'write'. 'read' is for capabilities that just let you view things. 'write' for capabilities that let you change things.

===contextlevel===

The context level where this capability is most relevant. If you are writing a module this will almost always be [[Context|CONTEXT_MODULE]]. (This does not have much effect. It is just used to sort and group capabilities on the define roles and override roles pages.)

===archetypes===

This section defines, for each role type, what default permissions those roles should be given when your module is first installed (or when a new capability is detected on upgrade).

Normally, you just add one line for each role that you want to give the capability to. The line should look like 'roletype' => CAP_ALLOW. Just leave out roles that you do not want to get the capability by default. Very exceptionally, you may need to specify a default permission of CAP_PREVENT, CAP_PROHIBIT.

Note that once a capability is established, permissions will not be automatically overwritten when a module is updated. If permissions have changed, an administrator must manually change or force capabilities to be [[:en:Manage_roles#Reset_role_to_defaults|reset to default]] for a role.

If you don't want to specify any roles that will be given your capability by default, you can pass a blank array to the 'archetypes' parameter:
<code php>
'mod/newmodule:dosomething' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array()
),
</code>

==2. Get Moodle to load the updated capabilities==

The capabilities you defined are only read (and copied into the Moodle database) when your module is installed or upgraded. So every time you edit the db/access.php file you must
# Increase your module's version number by editing the file mod/<<NEWMODULE>>/version.php.
# Go to the the Administration ► Notifications page, and click through the steps to let Moodle upgrade itself. You should see the name of your module in one of the steps.

==3. Checking the capability in your code==

In order to check whether the current user has a particular capability, you need to use the has_capability function. To do that, first you have to get the appropriate context. In this case, it will be a module context.

1. First we need to get the $cm id, and verify that it is correct (there are lots of different ways you might do this, this is only an example.
<code php>
$cmid = required_param('cmid', PARAM_INT);
if (!$cm = get_coursemodule_from_id('<<NEWMODULE>>', $cmid)) {
error("Course module ID was incorrect");
}
</code>

2. Then you get the module context:
<code php>
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
</code>

3. Finally, you can actually check the permission
<code php>
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {
</code>

Normally, you do 1. and 2. once at the top of a script, and then call has_capability as needed within the script with the appropriate capabilities.

===Useful variations===

====Controlling overall access to a script====

Suppose you have a page that should only be available to users with a particular capability. For example, only users with mod/quiz:viewreports should be able to access mod/quiz/report.php. In cases like this, you can use the require_capability function:
<code php>
require_capability($capability, $context);
</code>
near the top of your script. (As soon as you have got the context and called require_login is a good time.) All this does internally is
<code php>
if (!has_capability($capability, $context)) {
// Display error and exit.
}
</code>
but using require_capability makes your code simpler and is recommended. (Of course, anywhere you might print a link to a page like this, you should only print the link if the user has the right capability.)

====Getting a list of users with a capability====

Suppose you need to get a list of all the users with a particular capability. (For example, the quiz reports list all the users with the mod/quiz:attempt capability. Then you can use the get_users_by_capability function.

====Checking the permissions of another user====

There is an optional 3rd parameter to has_capability that you can use to check another user's permissions:
<code php>
has_capability($capability, $context, $otheruser->id);
</code>

====Excluding administrators====

Administrators have a magic 'moodle/site:doanything' capability that gives them every other capability. If you wish to disable that magic override for one particular capability check, you can use the optional 4th parameter to has capability:
<code php>
has_capability($capability, $context, NULL, false);
</code>
However, you normally should not do this.

====Performance considerations====

The has_capability function has been carefully optimised, and is pretty fast and you should not really worry. However, it has to perform a fairly complex computation, and if you are going to make exactly the same has_capability call several times in a page (perhaps in a loop) it is probably worth moving the permission check outside the loop. For example don't do:
<code php>
foreach ($attempts as $attempt) {
if (has_capability('mod/quiz:viewreports', $context)) {
// ...
}
}
</code>
Instead do
<code php>
$canviewreports = has_capability('mod/quiz:viewreports', $context);
foreach ($attempts as $attempt) {
if ($canviewreports) {
// ...
}
}
</code>

get_users_by_capability is a very expensive computation. If you are calling it more than once in your script, you are probably doing something wrong ;-)

==See also==

* [[Access API]]
* [[Roles]]
* [[Hardening_new_Roles_system]] - information about risks
* [[NEWMODULE_Documentation]] - NEWMODULE Documentation front page

[[Category:Roles]]

NEWMODULE Adding capabilities

2018-04-25T13:37:47Z

Libertymoodle: /* archetypes */

{{New_Module}}
In order to add a capabilities for your <<NEWMODULE>> you need to:

==1. Create a file access.php in the <<NEWMODULE>>/db directory==

This should contain a list of the capabilities that you want to define. For example:

<code php>
$capabilities = array(
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
)
),

// Add more capabilities here ...
)
</code>

The various parts of the capability definition are:

===Capability name ('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>)===

This is the internal name used for this this capability. In addition to this internal name, you should also add the language string <<NEWMODULE>>:<<CAPABILITYNAME>> to your module's language file, to give the capability a name that users will see in the interface.

===riskbitmask===

Allowing people to do various things sometimes requires introducing possible security risks. For example, if you can post to a forum, you can post unsolicited advertising. To a certain extent users have to be trusted. To help administrators and teachers know what the issues are, each capability should list any associated risks. See [[Hardening_new_Roles_system]]. will be reflected in the list of icons of each row of the 'Override permissions'->roles page.

Technically, this value is a bit field, so you should combine the relevant risks constants with the '|' operator. So typical values might be:
* RISK_SPAM
* RISK_PERSONAL | RISK_XSS | RISK_DATALOSS

===captype===

Should be either 'read' or 'write'. 'read' is for capabilities that just let you view things. 'write' for capabilities that let you change things.

===contextlevel===

The context level where this capability is most relevant. If you are writing a module this will almost always be [[Context|CONTEXT_MODULE]]. (This does not have much effect. It is just used to sort and group capabilities on the define roles and override roles pages.)

===archetypes===

This section defines, for each role type, what default permissions those roles should be given when your module is first installed (or when a new capability is detected on upgrade).

Normally, you just add one line for each role that you want to give the capability to. The line should look like 'roletype' => CAP_ALLOW. Just leave out roles that you do not want to get the capability by default. Very exceptionally, you may need to specify a default permission of CAP_PREVENT, CAP_PROHIBIT.

Note that once a capability is established, permissions will not be automatically overwritten when a module is updated. If permissions have changed, an administrator must manually change or force capabilities to be [[:en:Manage_roles#Reset_role_to_defaults|reset to default]] for a role.

If you don't want to specify any roles that will be given your capability by default you can pass a blank array to the 'archetypes' parameter:
<code php>
'mod/newmodule:dosomething' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array()
),
</code>

==2. Get Moodle to load the updated capabilities==

The capabilities you defined are only read (and copied into the Moodle database) when your module is installed or upgraded. So every time you edit the db/access.php file you must
# Increase your module's version number by editing the file mod/<<NEWMODULE>>/version.php.
# Go to the the Administration ► Notifications page, and click through the steps to let Moodle upgrade itself. You should see the name of your module in one of the steps.

==3. Checking the capability in your code==

In order to check whether the current user has a particular capability, you need to use the has_capability function. To do that, first you have to get the appropriate context. In this case, it will be a module context.

1. First we need to get the $cm id, and verify that it is correct (there are lots of different ways you might do this, this is only an example.
<code php>
$cmid = required_param('cmid', PARAM_INT);
if (!$cm = get_coursemodule_from_id('<<NEWMODULE>>', $cmid)) {
error("Course module ID was incorrect");
}
</code>

2. Then you get the module context:
<code php>
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
</code>

3. Finally, you can actually check the permission
<code php>
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {
</code>

Normally, you do 1. and 2. once at the top of a script, and then call has_capability as needed within the script with the appropriate capabilities.

===Useful variations===

====Controlling overall access to a script====

Suppose you have a page that should only be available to users with a particular capability. For example, only users with mod/quiz:viewreports should be able to access mod/quiz/report.php. In cases like this, you can use the require_capability function:
<code php>
require_capability($capability, $context);
</code>
near the top of your script. (As soon as you have got the context and called require_login is a good time.) All this does internally is
<code php>
if (!has_capability($capability, $context)) {
// Display error and exit.
}
</code>
but using require_capability makes your code simpler and is recommended. (Of course, anywhere you might print a link to a page like this, you should only print the link if the user has the right capability.)

====Getting a list of users with a capability====

Suppose you need to get a list of all the users with a particular capability. (For example, the quiz reports list all the users with the mod/quiz:attempt capability. Then you can use the get_users_by_capability function.

====Checking the permissions of another user====

There is an optional 3rd parameter to has_capability that you can use to check another user's permissions:
<code php>
has_capability($capability, $context, $otheruser->id);
</code>

====Excluding administrators====

Administrators have a magic 'moodle/site:doanything' capability that gives them every other capability. If you wish to disable that magic override for one particular capability check, you can use the optional 4th parameter to has capability:
<code php>
has_capability($capability, $context, NULL, false);
</code>
However, you normally should not do this.

====Performance considerations====

The has_capability function has been carefully optimised, and is pretty fast and you should not really worry. However, it has to perform a fairly complex computation, and if you are going to make exactly the same has_capability call several times in a page (perhaps in a loop) it is probably worth moving the permission check outside the loop. For example don't do:
<code php>
foreach ($attempts as $attempt) {
if (has_capability('mod/quiz:viewreports', $context)) {
// ...
}
}
</code>
Instead do
<code php>
$canviewreports = has_capability('mod/quiz:viewreports', $context);
foreach ($attempts as $attempt) {
if ($canviewreports) {
// ...
}
}
</code>

get_users_by_capability is a very expensive computation. If you are calling it more than once in your script, you are probably doing something wrong ;-)

==See also==

* [[Access API]]
* [[Roles]]
* [[Hardening_new_Roles_system]] - information about risks
* [[NEWMODULE_Documentation]] - NEWMODULE Documentation front page

[[Category:Roles]]

NEWMODULE Adding capabilities

2018-04-25T13:36:04Z

Libertymoodle: /* Add archetypes array */

{{New_Module}}
In order to add a capabilities for your <<NEWMODULE>> you need to:

==1. Create a file access.php in the <<NEWMODULE>>/db directory==

This should contain a list of the capabilities that you want to define. For example:

<code php>
$capabilities = array(
'mod/<<NEWMODULE>>:<<CAPABILITYNAME>>' => array(
'riskbitmask' => RISK_SPAM | RISK_PERSONAL | RISK_XSS | RISK_CONFIG,
'captype' => 'write',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'manager' => CAP_ALLOW
)
),

// Add more capabilities here ...
)
</code>

The various parts of the capability definition are:

===Capability name ('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>)===

This is the internal name used for this this capability. In addition to this internal name, you should also add the language string <<NEWMODULE>>:<<CAPABILITYNAME>> to your module's language file, to give the capability a name that users will see in the interface.

===riskbitmask===

Allowing people to do various things sometimes requires introducing possible security risks. For example, if you can post to a forum, you can post unsolicited advertising. To a certain extent users have to be trusted. To help administrators and teachers know what the issues are, each capability should list any associated risks. See [[Hardening_new_Roles_system]]. will be reflected in the list of icons of each row of the 'Override permissions'->roles page.

Technically, this value is a bit field, so you should combine the relevant risks constants with the '|' operator. So typical values might be:
* RISK_SPAM
* RISK_PERSONAL | RISK_XSS | RISK_DATALOSS

===captype===

Should be either 'read' or 'write'. 'read' is for capabilities that just let you view things. 'write' for capabilities that let you change things.

===contextlevel===

The context level where this capability is most relevant. If you are writing a module this will almost always be [[Context|CONTEXT_MODULE]]. (This does not have much effect. It is just used to sort and group capabilities on the define roles and override roles pages.)

===archetypes===

This section defines, for each role type, what default permissions those roles should be given when your module is first installed (or when a new capability is detected on upgrade).

Normally, you just add one line for each role that you want to give the capability to. The line should look like 'roletype' => CAP_ALLOW. Just leave out roles that you do not want to get the capability by default. Very exceptionally, you may need to specify a default permission of CAP_PREVENT, CAP_PROHIBIT.

Note that once a capability is established, permissions will not be automatically overwritten when a module is updated. If permissions have changed, an administrator must manually change or force capabilities to be [[:en:Manage_roles#Reset_role_to_defaults|reset to default]] for a role.

If you don't want to specify any roles that will be given your capability by default you can pass a blank array to the 'archetypes' parameter:
<code php>
'mod/newmodule:dosomething' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array()
),
</code>

==2. Get Moodle to load the updated capabilities==

The capabilities you defined are only read (and copied into the Moodle database) when your module is installed or upgraded. So every time you edit the db/access.php file you must
# Increase your module's version number by editing the file mod/<<NEWMODULE>>/version.php.
# Go to the the Administration ► Notifications page, and click through the steps to let Moodle upgrade itself. You should see the name of your module in one of the steps.

==3. Checking the capability in your code==

In order to check whether the current user has a particular capability, you need to use the has_capability function. To do that, first you have to get the appropriate context. In this case, it will be a module context.

1. First we need to get the $cm id, and verify that it is correct (there are lots of different ways you might do this, this is only an example.
<code php>
$cmid = required_param('cmid', PARAM_INT);
if (!$cm = get_coursemodule_from_id('<<NEWMODULE>>', $cmid)) {
error("Course module ID was incorrect");
}
</code>

2. Then you get the module context:
<code php>
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
</code>

3. Finally, you can actually check the permission
<code php>
if (has_capability('mod/<<NEWMODULE>>:<<CAPABILITYNAME>>', $context)) {
</code>

Normally, you do 1. and 2. once at the top of a script, and then call has_capability as needed within the script with the appropriate capabilities.

===Useful variations===

====Controlling overall access to a script====

Suppose you have a page that should only be available to users with a particular capability. For example, only users with mod/quiz:viewreports should be able to access mod/quiz/report.php. In cases like this, you can use the require_capability function:
<code php>
require_capability($capability, $context);
</code>
near the top of your script. (As soon as you have got the context and called require_login is a good time.) All this does internally is
<code php>
if (!has_capability($capability, $context)) {
// Display error and exit.
}
</code>
but using require_capability makes your code simpler and is recommended. (Of course, anywhere you might print a link to a page like this, you should only print the link if the user has the right capability.)

====Getting a list of users with a capability====

Suppose you need to get a list of all the users with a particular capability. (For example, the quiz reports list all the users with the mod/quiz:attempt capability. Then you can use the get_users_by_capability function.

====Checking the permissions of another user====

There is an optional 3rd parameter to has_capability that you can use to check another user's permissions:
<code php>
has_capability($capability, $context, $otheruser->id);
</code>

====Excluding administrators====

Administrators have a magic 'moodle/site:doanything' capability that gives them every other capability. If you wish to disable that magic override for one particular capability check, you can use the optional 4th parameter to has capability:
<code php>
has_capability($capability, $context, NULL, false);
</code>
However, you normally should not do this.

====Performance considerations====

The has_capability function has been carefully optimised, and is pretty fast and you should not really worry. However, it has to perform a fairly complex computation, and if you are going to make exactly the same has_capability call several times in a page (perhaps in a loop) it is probably worth moving the permission check outside the loop. For example don't do:
<code php>
foreach ($attempts as $attempt) {
if (has_capability('mod/quiz:viewreports', $context)) {
// ...
}
}
</code>
Instead do
<code php>
$canviewreports = has_capability('mod/quiz:viewreports', $context);
foreach ($attempts as $attempt) {
if ($canviewreports) {
// ...
}
}
</code>

get_users_by_capability is a very expensive computation. If you are calling it more than once in your script, you are probably doing something wrong ;-)

==See also==

* [[Access API]]
* [[Roles]]
* [[Hardening_new_Roles_system]] - information about risks
* [[NEWMODULE_Documentation]] - NEWMODULE Documentation front page

[[Category:Roles]]

SCORM reports

2018-02-28T07:05:51Z

Libertymoodle: /* Add Category */

{{Moodle 2.2}}
== Introduction ==
SCORM reports were converted to a pluggable architecture as of MOODLE 2.2. The original documentation of the project can be found at [https://docs.moodle.org/dev/SCORM_reporting_improvements SCORM Reporting Improvements]. Scorm Reports define a way for developer to develop reports of their own for the scorm module. The rest of this page deals with the details of how to develop such a report.
== Template ==
Here is a basic template for scorm report plugin on [https://github.com/ankitagarwal/scorm_report_template Github]
== File structure ==
Each plugin is allowed to have following files and folders:

=== Mandatory Files ===
* classes/report.php
* lang/xx/scormreport_pluginname.php

=== Other Optional Files ===
* Version.php
* db/install.php
* db/install.xml
* db/upgrade.php
* db/access.php
Please refer [[Upgrade API]] and [[Access API]] to understand the working of above files.

As you might have noticed the file structure for scorm report plugin is similar to any other standard plugin in Moodle. The only differences are:-
* There must be a file classes/report.php implementing class \scormreport_yourreport\report that must extend the default reporting class "\mod_scorm\report" and the extended class must implement the method "display($scorm, $cm, $course, $download)", which should handle the core reporting feature.
* The lang file is not optional. That is, each plugin must define the string "pluginname" in the lang files.

== Naming Conventions ==
Following Naming conventions should be kept in mind while writing a scorm report plugin:-
* Folder name should be same as pluginname
* Name of the extended class should be in format \scormreport_myreport\report
* \scormreport_myreport\report must implement the function
<code php>
function display($scorm, $cm, $course, $download) {}
</code>
* Each plugin must define the string "pluginname" in the language files.

== See Also ==
[https://docs.moodle.org/dev/SCORM_reporting_improvements SCORM Reporting Improvements] Original GSOC 2011 Project Documentation
=== User Docs ===
[https://docs.moodle.org/en/Using_SCORM Using SCORM]

[https://docs.moodle.org/en/SCORM_FAQ SCORM FAQ]

[https://docs.moodle.org/en/SCORM_module SCORM Module]

[[Category:SCORM]]
[[Category:Tutorial]]
[[Category:Plugins]]

lib/formslib.php Form Definition

2017-12-12T07:11:27Z

Libertymoodle: /* autocomplete */

{{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()'' 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 definition 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.

Note that the definition function is called when the form class is instantiated. There is no option to (say) manipulate data in the class (that may affect the rendering of the form) between instantiating the form and calling any other methods.

<code php>
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {

function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement()... // Add elements to your form
...
} // Close the function
} // Close the class
</code>
===Passing parameters to the Form===

The constructor for ''moodleform'' allows a number of parameters including one (''$customdata'') to permit an array of arbitrary data to be passed to your form.

For example, you can pass the data "$email" and "$username" to the Form's class for use inside (say) the definition.
<code php>
...
$mform_simple = new simplehtml_form( null, array('email'=>$email, 'username'=>$username ) );
...
</code>
(the first parameter is $action, ''null'' will case the form action to be determined automatically)

Secondly, inside the form definition you can use those parameters to set the default values to some of the form's fields
<code php>
...
$mform->addElement('text', 'email', get_string('email'), 'maxlength="100" size="25" ');
$mform->setType('email', PARAM_NOTAGS);
$mform->addRule('email', get_string('missingemail'), 'required', null, 'server');
// Set default value by using a passed parameter
$mform->setDefault('email',$this->_customdata['email']);
...
</code>

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a ''legend''. <br />
('''Note''': Some themes turn off legends on admin setting pages by using CSS: <nowiki>#adminsettings legend {display:none;}</nowiki>.)

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

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

{{Moodle 2.5}}
Since Moodle 2.5 fieldsets without any required fields are collapsed by default. To display these fieldsets on page load, use:
<code php>
$mform->setExpanded('foo')
</code>

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

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

==addElement==

Use the addElement method to add 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 ===

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

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

=== autocomplete ===
{{Moodle 3.1}}
Available since Moodle 3.1

<code php>
$searchareas = \core_search\manager::get_search_areas_list(true);
$areanames = array();
foreach ($searchareas as $areaid => $searcharea) {
$areanames[$areaid] = $searcharea->get_visible_name();
}
$options = array(
'multiple' => true,
'noselectionstring' => get_string('allareas', 'search'),
);
$mform->addElement('autocomplete', 'areaids', get_string('searcharea', 'search'), $areanames, $options);
</code>

The autocomplete element is an advanced form element that supports server-side searching - or simple filtering of a predefined list of options. Some benefits of using this form element are that it handles very large datasets extremely well - it has great accessibility built in - and it gives a good user experience. If you have so much data you need to build pagination into a page - you could probably come up with a better design using this. The simplest way to use it is compatible with the standard 'select' form element. You give it a list of options and some parameters to configure how it behaves. The valid parameters for this simple mode of operation are:
* multiple (boolean) - Allow more than one selected item. The data coming from the form will be an array in this case.
* noselectionstring (string) - The text to display when nothing is selected.
* showsuggestions (boolean) - Do not show the list of suggestions when the user starts typing.
* placeholder (string) - The text to show in the search box when it is empty.
* casesensitive (boolean) - Is the search case sensitive ?
* tags (boolean) - This changes the behaviour so that the user can create new valid entries in the list by typing them and pressing enter.
* ajax (string) - This string is the name of an AMD module that can fetch and format results.

More explanation on the 'ajax' option. This should be the name of an AMD module that implements 2 functions:
<code javascript>
/**
* Source of data for Ajax element.
*
* @param {String} selector The selector of the auto complete element.
* @param {String} query The query string.
* @param {Function} callback A callback function receiving an array of results.
* @return {Void}
*/
transport: function(selector, query, callback) ...

/**
* Process the results for auto complete elements.
*
* @param {String} selector The selector of the auto complete element.
* @param {Array} results An array or results.
* @return {Array} New array of results.
*/
processResults: function(selector, results)...

</code>
A good example is here: [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/amd/src/frameworks_datasource.js admin/tool/lp/amd/src/frameworks_datasource.js]

When using the ajax option in an mform with validation etc - it is recommended to sub-class the php class "MoodleQuickForm_autocomplete" so that you can provide a list of name and
values to populate the form element if the form is re-displayed due to a validation error. An example is [https://github.com/moodle/moodle/blob/MOODLE_31_STABLE/admin/tool/lp/classes/form/framework_autocomplete.php admin/tool/lp/classes/form/framework_autocomplete.php].

We have provided several useful subclasses of this form element already that are simple to use (course and tags).

<code php>
// Course example.
// Valid options are:
// 'multiple' - boolean multi select
// 'exclude' - array or int, list of course ids to never show
// 'requiredcapabilities' - array of capabilities. Uses ANY to combine them.
// 'limittoenrolled' - boolean Limits to enrolled courses.
// 'includefrontpage' - boolean Enables the frontpage to be selected.
$options = array('multiple' => true, 'includefrontpage' => true);
$mform->addElement('course', 'mappedcourses', get_string('courses'), $options);

// Tags
// Valid options are:
// 'showstandard' - boolean One of the core_tag_tag constants to say which tags to display
// 'component' - string The component name and itemtype define the tag area
// 'itemtype' - string The component name and itemtype define the tag area
$mform->addElement('tags', 'interests', get_string('interestslist'), array('itemtype' => 'user', 'component' => 'core'));
</code>

=== checkbox ===

<code php>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</code>

This is a simple checkbox. The third parameter for this element is the label to display on the left side of the form. You can also supply a string as a fourth parameter 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.

You can have a 5th parameter $attributes, as on other elements.

'''BEWARE:''' Unchecked checkboxes return nothing at all (as if they didn't exist). This can surprise the unwary. You may wish to use advcheckbox instead, which does return a value when not checked. 'Advcheckbox' eliminates this problem.

==== advcheckbox ====
<code php>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), 'Label displayed after checkbox', array('group' => 1), array(0, 1));
</code>

Similar to the checkbox above, but with some important improvements:

# The (optional) 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[lib/formslib.php_add_checkbox_controller|checkbox controller]]
#The (optional) 6th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#It returns a 0 value when unchecked. Compare with the ordinary checkbox which does not return anything at all.

=== choosecoursefile ===
{{Moodle 1.9}}
<code php>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));
</code>

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

'''Note: This has been superceded by [[#filepicker|filepicker]] in Moodle 2.'''

<code php>
array('courseid' =>null, //if it is null (default then use global $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'
</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('maxlength' => 255, 'size' => 48)</code>
to control the maxlength / size of the text box (note size will default to 48 if not specified)

Finally, as this element is a group containing two elements (button + value), you can add validation rules by using the '''addGroupRule()''' method in this (complex) way:

<code php>$mform->addGroupRule('elementname', array('value' => array(array(list, of, rule, params, but, fieldname))));</code>

Where: '''"elementname"''' is the name of the choosecoursefile group element, '''"value"''' is the name of the text field within the group and the '''"list, of, addrule, params, but, fieldname"''' is exactly that, the list of fields in the normal addRule() function but ommiting the first one, the fieldname.

For example, the [http://cvs.moodle.org/moodle/mod/resource/type/file/resource.class.php?view=markup file/url resource type], uses one "choosecoursefile" element, and it controls the maximum length of the field (255) with this use of addGroupRule():

<code php>$mform->addGroupRule('reference', array('value' => array(array(get_string('maximumchars', '', 255), 'maxlength', 255, 'client'))));</code>

=== date_selector ===

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

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 :

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'optional' => false
);
</code>

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 ===

<code php>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</code>

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:

<code php>
array(
'startyear' => 1970,
'stopyear' => 2020,
'timezone' => 99,
'step' => 5
);
</code>

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.

===duration===
{{Moodle 2.0}}

<code php>
$mform->addElement('duration', 'timelimit', get_string('timelimit', 'quiz'));
</code>
This field type lets the user input an interval of time. It comprises a text field, where you can type a number, and a dropdown for selecting a unit (days, hours, minutes or seconds). When submitted the value is converted to a number of seconds.

You can add a fourth parameter to give options. At the moment the only option supported is here is an array of options. The defaults for the options is:
<code php>array('optional' => true)</code>

You can also pass an optional 5th parameter of attributes, as for other elements. The most useful way of using that is something like
<code php>array('size' => 5)</code>
to control the size of the text box.

=== editor ===

This replaces the old htmleditor field type. It allows the user to enter rich text content in a variety of formats.

<code php>
$mform->addElement('editor', 'fieldname', get_string('labeltext', 'langfile'));
$mform->setType('fieldname', PARAM_RAW);
</code>

NOTE: It won't work properly without the setType() as shown.

If you would like to let the user use the filepicker to upload images etc. that are used in the content, then see [[Using_the_File_API_in_Moodle_forms]].

You can supply a fourth param to htmleditor of an array of options that are mostly related to file handling:

<code php>
array(
'subdirs'=>0,
'maxbytes'=>0,
'maxfiles'=>0,
'changeformat'=>0,
'context'=>null,
'noclean'=>0,
'trusttext'=>0,
'enable_filemanagement' => true);
</code>

The option 'enable_filemanagement' will display the file management button on true and remove it on false.

To save the data if you don't care about files:
<code php>
$formdata = $mform->get_data();
$text = $formdata->fieldname['text'];
$format = $formdata->fieldname['format'];
</code>

Note: Because the text editor might be "Atto" (depending on user preferences) and Atto has an "autosave" feature - it requires that the combination of $PAGE->url and this elementid are unique. If not, the autosaved text for a different form may be restored into this form.

=== file ===

File upload input box with browse button. In the form definition type

<code php>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</code>

after form submission and validation use

<code php>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</code>

If there is no requirement to save the file, you can read the file contents directly into a string as follows...

<code php>
$mform->get_file_content('attachment');
</code>

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

<code php>
$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');

</code>

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

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',..).

{{Moodle 2.0}}
File uploading was rewritten in 2.0. Please see inline docs for now. This page will be updated when the new API stabilises.

===filepicker===
{{Moodle 2.0}}
General replacement of ''file'' element.

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null, array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>
See also [[Using the File API in Moodle forms]]

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

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

=== html ===
You can add arbitrary HTML to your Moodle form:

<code php>
$mform->addElement('html', '<div class="qheader">');
</code>

See [http://moodle.org/mod/forum/discuss.php?d=126935 "Question: Can I put a moodleform inside a table td?"] for a concrete example.

=== htmleditor & format ===

These elements are now deprecated. Please use the [[#editor|editor]] field type instead.

===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.

===modvisible===
<pre>
$mform->addElement('modvisible', 'visible', get_string('visible'));
</pre>
This is a custom element for selecting a grade visibility in an activity mod update form.

===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 ===
{{Moodle 2.3}}
<code php>
$radioarray=array();
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = $mform->createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</code>

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.

It is possible to add help to individual radio buttons but this requires a custom template to be defined for the group elements. See MDL-15571.

Since 2.3 it cannot be statically called anymore, so we need to call createElement from $mform reference.

==== setDefault ====

To set the default for a radio button group as above use the following :

<code php>
$mform->setDefault('yesno', 0);
</code>

This would make the default 'no'.

===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.

It is also possible to create a select with certain options disabled, using [http://stackoverflow.com/questions/2138089/how-can-i-use-quickform-to-add-disabled-select-options/2150275#2150275 this technique].

You can set an 'onchange' attribute when adding or creating the select element:

$form->addElement('select', 'iselTest', 'Test Select:', $arrayOfOptions, array('onchange' => 'javascript:myFunctionToDoSomething();');

====multi-select====
<pre>
$select = $mform->addElement('select', 'colors', get_string('colors'), array('red', 'blue', 'green'), $attributes);
$select->setMultiple(true);
</pre>

=====setSelected=====

To set the default selected item in a select element, you can use the 'setSelected' method. The 'setSelected' can either get a value or an array of values.

<pre>
$options = array(
'ff0000' => 'Red',
'00ff00' => 'Green',
'0000ff' => 'Blue'
);
$select = $mform->addElement('select', 'colors', get_string('colors'), $options);
// This will select the colour blue.
$select->setSelected('0000ff');
</pre>

Or for multpi-selection:
<pre>
$skillsarray = array(
'val1' => 'Skill A',
'val2' => 'Skill B',
'val3' => 'Skill C'
);
$mform->addElement('select', 'md_skills', get_string('skills', 'metadata'), $skillsarray);
$mform->getElement('md_skills')->setMultiple(true);
// This will select the skills A and B.
$mform->getElement('md_skills')->setSelected(array('val1', 'val2'));
</pre>

However you probably don't want to do this. Instead you probably want to use setDefault, or set it using the form's setData method.

===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.

===selectwithlink===
<pre>
$options = array();
$mform->addElement('selectwithlink', 'scaleid', get_string('scale'), $options, null,
array('link' => $CFG->wwwroot.'/grade/edit/scale/edit.php?courseid='.$COURSE->id, 'label' => get_string('scalescustomcreate')));
</pre>
select type element with options containing link
===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 if 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', '', ' ', false);
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but 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 parameter 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'). Note the '''$this''' not '''$mform'''

<pre>
$this->add_action_buttons();
</pre>

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text input element. (For text labels, use the 'static' 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 an 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.

===recaptcha===
{{Moodle 1.9}}
<pre>
$mform->addElement('recaptcha', 'recaptcha_field_name', $attributes);
</pre>

Use this recaptcha element to reduce the spam risk in your forms. Third element here is a string or array of attributes. Take care to get an API key from http://recaptcha.net/api/getkey before using this element.

To check whether recaptcha is enabled at site level use:
<pre>
if (!empty($CFG->recaptchapublickey) && !empty($CFG->recaptchaprivatekey)) {
//recaptcha is enabled
}
</pre>

===tags===
{{Moodle 2.0}}

<pre>
$mform->addElement('tags', 'field_name', $lable, $options, $attributes);
</pre>

Used for editing a list of tags, for example on a blog post.

There is only one option available, 'display', which should be set to one of the contstants MoodleQuickForm_tags::ONLYOFFICIAL, NOOFFICIAL or DEFAULTUI. This controls whether the official tags are listed for easy selection, or a text area where arbitrary tags may be typed, or both. The default is both.

The value should be set/returned as an array of tags.

===grading===
<code php>
$mform->addElement('grading', 'advancedgrading', get_string('grade').':', array('gradinginstance' => $gradinginstance));
</code>

Custom element for advanced grading plugins.

When adding the 'grading' element to the form, developer must pass an object of class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be thrown.

===questioncategory===
<code php>
$mform->addElement('questioncategory', 'category', get_string('category', 'question'),
array('contexts'=>$contexts, 'top'=>true, 'currentcat'=>$currentcat, 'nochildrenof'=>$currentcat));
</code>
Creates a drop down element to select a question category.

Options are:
'''contexts''' - (required) context in which question appears
'''currentcat''' - (optional) course category
'''top''' - (optional) if true will put top categories on top
'''nochildrenof''' - (optional) Format categories into an indented list reflecting the tree structure

=== filetypes ===
{{Moodle 3.4}}
Available since Moodle 3.4

<code php>
$mform->addElement('filetypes', 'allowedfiletypes', get_string('allowedfiletypes', 'tool_myplugin'));
</code>

Creates an input element allowing the user to specify file types for the given purpose. The typical scenario is a setting that allows the teacher define a list of allowed file types submitted by students.

The element allows the user to either type the list of filetypes manually, or select the types from the list. Also supported is selecting the whole group of file types - such as "image". The element integrates with the [[Core filetypes]] system so all default types and groups are presented, as well as those [[:en:Working with files#Site administration settings|defined locally by the admin]].

As the list can be types in manually, the form processing code should always normalize it first via the provided utility methods:

<code php>
$formdata = $mform->get_data();
$filetypesutil = new \core_form\filetypes_util();
$allowedfiletypes = $filetypesutil->normalize_file_types($formdata->allowedfiletypes);
</code>

This always returns an array of recognized valid values. The original list can be separated by whitespace, end of lines, commas, colons and semicolons. During the normalization, values are converted to lowercase, empty valies and duplicates are removed. Glob evaluation is not supported.

The normalization should also happen if the previously defined list had been saved to the database and re-read for actual usage. The normalization output value can be directly used as the accepted_types option for the filepicker.

<code php>
$filetypesutil = new \core_form\filetypes_util();
$options['accepted_types'] = $filetypesutil->normalize_file_types($allowedfiletypes);
</code>

By default, user input is validated against the list of known file types and groups. This validation can be disabled via options.

'''Supported options'''

; onlytypes : Allow selection from these file types only; for example ['onlytypes' => ['web_image']].
; allowall : Allow to select 'All file types', defaults to true. Does not apply with onlytypes are set.
; allowunknown : Skip implicit validation against the list of known file types.

Example:

<code php>
$mform->addElement('filetypes', 'doctypes', get_string('doctypes', 'tool_myplugin'), ['onlytypes' => ['document'], 'allowunknown' => true]);
</code>

==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 a bad example (don't do this for real, use the 'optional' => true option of the date element): 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>

* If you want to put a group inside another array so that you can repeat items, use createElement instead of addGroup:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems);
</pre>

* By default, groups modify the names of elements inside them by appending a number. This is often unhelpful, for example if you want to use disabledIf on the element. To prevent this behaviour, set the last parameter to false when creating a group.:

<pre>
$group = $mform->createElement('group', 'groupname', get_string('label'), $groupitems, null, false);
</pre>

==addRule==
<pre>
$mform->addRule('elementname', get_string('error'), 'rule type', 'extraruledata', 'server'(default), false, false);
</pre>

The first param(element) is an element name and second(message) is the error message that will be displayed to the user.
The third parameter(type) is the type of rule. The fourth param(format) is used for extra data needed with some rules such as minlength and regex. The fifth parameter(validation) validates input data on server or client side, if validation is done on client side then it will be checked on the server side as well.

<pre>
* @param string $element Form element name
* @param string $message Message to display for invalid data
* @param string $type Rule type, use getRegisteredRules() to get types
* @param string $format (optional)Required for extra rule data
* @param string $validation (optional)Where to perform validation: "server", "client"
* @param boolean $reset Client-side validation: reset the form element to its original value if there is an error?
* @param boolean $force Force the rule to be applied, even if the target form element does not exist
</pre>

'''Common Rule Types'''
* required
* maxlength
* minlength
* rangelength
* email
* regex
* lettersonly
* alphanumeric
* numeric
* nopunctuation
* nonzero
* callback
* compare

===Server side and Client side===
In case you use the ''Client side'' validation option, you can mainly check for an empty or not input field. unless you write some ''Client side'' code which will probably be JavaScript functions to verify the data inside the input fields before it is submitted to the server. It could save some time if those functions are short, simple and quick to compute.
In case you need a more complex validation checks which relay on Moodle's internal PHP libraries (or other/external PHP libraries) you better use the ''Server side'' validation checks. Where you can query the DB, write complex PHP validation functions and much much more, that are not available (easily) when using JavaScript on the client's side.

==setHelpButton==
{{Moodle 1.9}}

<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();

==addHelpButton==
{{Moodle 2.0}}

<code php>
$mform->addHelpButton('api_key_field', 'api_key', 'block_extsearch');
</code>

In Moodle 2.0 the "setHelpButton" method has been deprecated in favor of the "addHelpButton" method, which has a simplified interface and uses $OUTPUT->help_icon() on the back end. The following parameters are expected:

<code php>
/**
* @param $elementname The name of the form element to add the help button for
* @param $identifier The identifier for the help string and its title (see below)
* @param $component The component name to look for the help string in
*/
</code>
Unlike in Moodle 1.9, it is no longer necessary to put your help pages in separate HTML files. Instead, the function looks for two strings:

# get_string($identifier, $component) // The title of the help page
# get_string("{$identifier}_help", $component) // The content of the help page

So you will need to have '''$identifier''' and '''{$identifier}_help''' defined in order for the help button to be created properly. For example the multiple choice question editing form has a button for shuffling the answers.
<code php>
$mform->addHelpButton('shuffleanswers', 'shuffleanswers', 'qtype_multichoice');
</code>
and so the language file includes the strings
<code php>
$string['shuffleanswers'] = 'Shuffle the choices?';
$string['shuffleanswers_help'] = 'If enabled,.....';
</code>
You can also add the language string like
<code php>
$string['shuffleanswers_link'] = 'question/shuffleanswers';
</code>
to add a link to more help on Moodle docs. See [[String_API]] for more information about help icons.

==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.

<pre>
$mform->addElement('editor', 'desc', get_string('description'));
$mform->setDefault('desc', array('text'=>$defaulttext));
</pre>

Note that when setting the default for an editor element you must use an array to define the default "text" value as shown above.

==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='1')

* 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 second 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', 'noitemselected', 'eq', 'in' or, if it is anything else, 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 'in' then we check to see if a selected item is in the given list or not. (This was introduced in Moodle 2.7+)
** If $condition is 'noitemselected' then we check to see whether nothing is selected in a dropdown list.

Examples:
// Disable my control unless a checkbox is checked.
$mform->disabledIf('mycontrol', 'somecheckbox');

// Disable my control if a checkbox '''is''' checked.
$mform->disabledIf('mycontrol', 'somecheckbox', 'checked');

// Disable my control when a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'eq', 42);

// Disable my control unless a dropdown has value 42.
$mform->disabledIf('mycontrol', 'someselect', 'neq', 42);

The possible choices here are in the dependency manager in lib/form/form.js.
===A tricky case===

You need to take care with disabledIf if you plan to use it with groups of checkboxes.

Let's say you have a group of 5 checkboxes and you want to enable a depending item such as a drop down menu only when the first and the last checkboxes are selected.

To fix ideas:

If the selection in the checkboxes group is:

mycheck_01 == 1
mycheck_02 == 0
mycheck_03 == 0
mycheck_04 == 0
mycheck_05 == 1

the depending item must be enabled while ANY OTHER COMBINATION must disable the drop down menu.

The following code will, apparently, fail:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'neq', '1');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'neq', '0');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'neq', '1');
</code>

In fact, once you get the drop down menu enabled, you are free to unselect mycheck_01 whilst still having the depending item enabled.
This apparent bug occurs because a non-checked checkbox behaves like a non existing mform element. So the js code will not find the element "mycheck_01" and will not apply the corresponding rule.

A working solution for this kind of issue seems to be:
<code php>
$mform->disabledIf('dropdownmenu', 'mycheck_01', 'notchecked');
$mform->disabledIf('dropdownmenu', 'mycheck_02', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_03', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_04', 'checked');
$mform->disabledIf('dropdownmenu', 'mycheck_05', 'notchecked');
</code>
To see a failing example as the one described, try the attachments provided in MDL-38975. See also in MDL-38975 for the working solution in action with modifications suggested by Eloy.

==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 contain multi-lang content. 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 *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_FLOAT is also available for decimal numbers but is not recommended for user input since it does not work for languages that use , as a decimal separator.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==disable_form_change_checker==

By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call

$mform->disable_form_change_checker()

==References==

* [http://www.midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide] by Keith Edmunds of Midnighthax.com
* [http://pear.php.net/manual/en/package.html.html-quickform.php PEAR::HTML_QuickForm manual]

[[Category:Formslib]]
[[Category:Interfaces]]

Using the File API in Moodle forms

2017-04-21T12:58:44Z

Libertymoodle: /* See also */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the corresponding [[Repository plugins|Repository plugin]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[File API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.
If you want a file that remains part of the Moodle storage and will reappear when you reopen the form, then you should use a filemanager instead (and restrict it to a single file, if necessary).

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null,
array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

To get the contents of the file:

<code php>
$content = $mform->get_file_content('userfile');
</code>

To get the name of the chosen file:

<code php>
$name = $mform->get_new_filename('userfile');
</code>

To save the chosen file to the server filesystem (such as to moodledata folder):

<code php>
$success = $mform->save_file('userfile', $fullpath, $override);
</code>

To store the chosen file in the Moodle files pool:

<code php>
$storedfile = $mform->save_stored_file('userfile', ...);
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'areamaxbytes' => 10485760, 'maxfiles' => 50,
'accepted_types' => array('document'), 'return_types'=> FILE_INTERNAL | FILE_EXTERNAL));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the size of each individual file.
;areamaxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/filestorage/file_types.mm moodle/lib/filestorage/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle.

As of 2.3 file_types.mm is no longer used, instead the file types are listed in <code>get_mimetypes_array()</code> in filelib.php (https://github.com/moodle/moodle/blob/master/lib/classes/filetypes.php).

Example usage: '''array('audio', 'video', 'document')''', you can include file extensions as well, for example: '''array('.txt', '.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new stdClass;
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');

file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));

$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment',
$entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two ways of using the editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array. note that context is the best, most local context you have available.
#:<code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes, 'context'=>$context);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet
#:<code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data
#:<code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data
#:<code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes;
// Could also use $CFG->maxbytes if you are not coding within a course context

$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true,
'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'),
array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$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->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'),
'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null,
$definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'),
null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2',
get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly
* Make sure $definitionoptions has context parameter, else system context is used and editor will not respect filter settings.

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository plugins]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue
* [https://moodle.org/mod/forum/discuss.php?d=207748 Adding a text editor to a Moodle form]
* [https://moodle.org/mod/forum/discuss.php?d=157953#p692822 Button actions in Moodle form]
* [https://moodle.org/mod/forum/discuss.php?d=351013#p1416554 File Picker]

[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2017-02-10T13:10:55Z

Libertymoodle: /* See also - typo */

Using the File API in Moodle forms

2017-02-10T13:10:26Z

Libertymoodle: /* See also links */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the corresponding [[Repository plugins|Repository plugin]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[File API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.
If you want a file that remains part of the Moodle storage and will reappear when you reopen the form, then you should use a filemanager instead (and restrict it to a single file, if necessary).

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null,
array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

To get the contents of the file:

<code php>
$content = $mform->get_file_content('userfile');
</code>

To get the name of the chosen file:

<code php>
$name = $mform->get_new_filename('userfile');
</code>

To save the chosen file to the server filesystem (such as to moodledata folder):

<code php>
$success = $mform->save_file('userfile', $fullpath, $override);
</code>

To store the chosen file in the Moodle files pool:

<code php>
$storedfile = $mform->save_stored_file('userfile', ...);
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'areamaxbytes' => 10485760, 'maxfiles' => 50,
'accepted_types' => array('document'), 'return_types'=> FILE_INTERNAL | FILE_EXTERNAL));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the size of each individual file.
;areamaxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/filestorage/file_types.mm moodle/lib/filestorage/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle.

As of 2.3 file_types.mm is no longer used, instead the file types are listed in <code>get_mimetypes_array()</code> in filelib.php (https://github.com/moodle/moodle/blob/master/lib/classes/filetypes.php).

Example usage: '''array('audio', 'video', 'document')''', you can include file extensions as well, for example: '''array('.txt', '.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new stdClass;
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');

file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));

$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment',
$entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two ways of using the editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array. note that context is the best, most local context you have available.
#:<code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes, 'context'=>$context);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet
#:<code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data
#:<code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data
#:<code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes;
// Could also use $CFG->maxbytes if you are not coding within a course context

$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true,
'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'),
array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$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->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'),
'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null,
$definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'),
null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2',
get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly
* Make sure $definitionoptions has context parameter, else system context is used and editor will not respect filter settings.

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository plugins]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue
* [https://moodle.org/mod/forum/discuss.php?d=207748 Adding a text editor to a Moodle form]
* [https://moodle.org/mod/forum/discuss.php?d=157953#p692822 Button actions in moodle form]

[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2017-02-08T09:14:17Z

Libertymoodle: /* Simple use - wiki formatting */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the corresponding [[Repository plugins|Repository plugin]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[File API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.
If you want a file that remains part of the Moodle storage and will reappear when you reopen the form, then you should use a filemanager instead (and restrict it to a single file, if necessary).

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null,
array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

To get the contents of the file:

<code php>
$content = $mform->get_file_content('userfile');
</code>

To get the name of the chosen file:

<code php>
$name = $mform->get_new_filename('userfile');
</code>

To save the chosen file to the server filesystem (such as to moodledata folder):

<code php>
$success = $mform->save_file('userfile', $fullpath, $override);
</code>

To store the chosen file in the Moodle files pool:

<code php>
$storedfile = $mform->save_stored_file('userfile', ...);
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'areamaxbytes' => 10485760, 'maxfiles' => 50,
'accepted_types' => array('document'), 'return_types'=> FILE_INTERNAL | FILE_EXTERNAL));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the size of each individual file.
;areamaxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/filestorage/file_types.mm moodle/lib/filestorage/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle.

As of 2.3 file_types.mm is no longer used, instead the file types are listed in <code>get_mimetypes_array()</code> in filelib.php (https://github.com/moodle/moodle/blob/master/lib/classes/filetypes.php).

Example usage: '''array('audio', 'video', 'document')''', you can include file extensions as well, for example: '''array('.txt', '.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new stdClass;
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');

file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));

$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment',
$entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two ways of using the editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array. note that context is the best, most local context you have available.
#:<code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles, 'maxbytes'=>$maxbytes, 'context'=>$context);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet
#:<code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'), null, $textfieldoptions);</code>
# prepare data
#:<code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data
#:<code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context, 'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes;
// Could also use $CFG->maxbytes if you are not coding within a course context

$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true,
'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'),
array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$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->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'),
'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null,
$definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'),
null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2',
get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly
* Make sure $definitionoptions has context parameter, else system context is used and editor will not respect filter settings.

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository plugins]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue
* [http://moodle.org/mod/forum/discuss.php?d=207748 Adding a text editor to a Moodle form]

[[Category:Files]]
[[Category:Repositories]]

Using the File API in Moodle forms

2017-02-08T08:17:36Z

Libertymoodle: /* filepicker - usage info */

{{Moodle 2.0}}

This document shows you exactly how to use Moodle forms to get files from users in a standard and secure way.

==Overview==

In Moodle 2.0 all files are stored in a central database accessible via the [[File API|File API]], and every file is associated with a component and a "file area" in Moodle, such as a particular module.

A common use case is to provide a form (using Moodle's [[lib/formslib.php|Forms API]]) which allows users to upload or import files as attachments or media embedded into HTML.

Normally this works like this:
# User starts creation or re-edits an existing item in Moodle (eg forum post, resource, glossary entry etc)
# User presses some sort of button to browse for new files to attach or embed
# User sees our "Choose file..." dialog, which contains one or more repository instances.
# User chooses a file, the corresponding [[Repository plugins|Repository plugin]] takes care of copying the file into a "draft file area" within Moodle
# File appears in the text or as an attachment in the form.
# When the user hits save, the [[File API|File API]] is invoked to move the file from the draft file area into a permanent file area associated with that data

This document shows you exactly how to use Moodle forms to interact with users in a standard and secure way.

If you just want to write code to manipulate Moodle files internally (without user input) then see [[File API]].

==Form elements==

In Moodle 2.0 there are three file-related form elements for interacting with users:

# filemanager - the way to attach one or more files as a set
# editor - the way to specify a textarea with a HTML editor, and all the handling of images and movies within that HTML
# filepicker - a way to specify one file for the case when you want to process the file and throw it away

In Moodle 1.9 there were two other types which are now '''deprecated''' (they work, but please do not use these anymore)
# file - used to just allow a normal file upload from the desktop only.
# htmleditor - this old method of embedding a HTML editor in a textarea is not able to support repositories etc.

===filepicker===

File picker (''filepicker'') is a direct replacement of the older ''file'' formslib element.

It is intended for situations when you want the user to upload '''one''' file so you can process it and delete it, such as when you are importing data from a CSV file.
If you want a file that remains part of the Moodle storage and will reappear when you reopen the form, then you should use a filemanager instead (and restrict it to a single file, if necessary).

==== Using the filepicker element ====

<code php>
$mform->addElement('filepicker', 'userfile', get_string('file'), null,
array('maxbytes' => $maxbytes, 'accepted_types' => '*'));
</code>

==== Obtain the chosen file ====

To get the contents of the file:

<code php>
$content = $mform->get_file_content('userfile');
</code>

To get the name of the chosen file:

<code php>
$name = $mform->get_new_filename('userfile');
</code>

To save the chosen file to the server filesystem (such as to moodledata folder):

<code php>
$success = $mform->save_file('userfile', $fullpath, $override);
</code>

To store the chosen file in the Moodle files pool:

<code php>
$storedfile = $mform->save_stored_file('userfile', ...);
</code>

=== filemanager ===

The File Manager element improves on file picker by allowing you to manage more than one file. It is expected that the files will be stored permanently for future use (such as forum and glossary attachments).

==== Add file manager element ====

Example:
<code php>
$mform->addElement('filemanager', 'attachments', get_string('attachment', 'moodle'), null,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'areamaxbytes' => 10485760, 'maxfiles' => 50,
'accepted_types' => array('document'), 'return_types'=> FILE_INTERNAL | FILE_EXTERNAL));
</code>

Here are the fields for filemanager:

;'filemanager':This is a filemanager element :)
;elementname:The unique name of the element in the form
;elementlabel:The label string that users see
;attributes:(leave it as null)
;options: an array of further options for the filepicker (see below)

The options array can contain:

;subdirs:(Default 1) Are subdirectories allowed? (true or false)
;maxbytes:(Default 0) Restricts the size of each individual file.
;areamaxbytes:(Default 0) Restricts the total size of all the files.
;maxfiles:(Default -1) Restricts the total number of files.
;accepted_types:(Default *) You can specify what file types are accepted by filemanager. All current file types are listed in this file: [http://cvs.moodle.org/moodle/lib/filestorage/file_types.mm moodle/lib/filestorage/file_types.mm]. This is a [http://freemind.sourceforge.net/wiki/index.php/Main_Page freemind] file: if it is edited the changes will be immediately reflected in Moodle.

As of 2.3 file_types.mm is no longer used, instead the file types are listed in <code>get_mimetypes_array()</code> in filelib.php (https://github.com/moodle/moodle/blob/master/lib/classes/filetypes.php).

Example usage: '''array('audio', 'video', 'document')''', you can include file extensions as well, for example: '''array('.txt', '.jpg', 'audio')'''.

==== Load existing files into draft area ====

<code php>
if (empty($entry->id)) {
$entry = new stdClass;
$entry->id = null;
}

$draftitemid = file_get_submitted_draft_itemid('attachments');

file_prepare_draft_area($draftitemid, $context->id, 'mod_glossary', 'attachment', $entry->id,
array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));

$entry->attachments = $draftitemid;

$mform->set_data($entry);

</code>

==== Store updated set of files ====

<code php>
if ($data = $mform->get_data()) {
// ... store or update $entry
file_save_draft_area_files($data->attachments, $context->id, 'mod_glossary', 'attachment',
$entry->id, array('subdirs' => 0, 'maxbytes' => $maxbytes, 'maxfiles' => 50));
}
</code>

===editor===
There are two ways of using the editor element in code, the first one is easier but expects some standardized fields. The second method is more low level.

====Simple use====
# name database fields: ''textfield'', ''textfieldformat'' (and ''textfieldtrust'' if required)
# create options array. note that context is the best, most local context you have available. <code php>$textfieldoptions = array('trusttext'=>true, 'subdirs'=>true, 'maxfiles'=>$maxfiles,
'maxbytes'=>$maxbytes, 'context'=>$context);</code>
# add editor ''textfield_editor'' to moodle form, pass options through custom data in form constructor, set $data->id to null if data not exist yet <code php>$mform->addElement('editor', 'textfield_editor', get_string('fieldname', 'somemodule'),
null, $textfieldoptions);</code>
# prepare data <code php>$data = file_prepare_standard_editor($data, 'textfield', $textfieldoptions, $context,
'mod_somemodule', 'somearea', $data->id);</code>
# get submitted data and after inserting/updating of data <code php>$data = file_postupdate_standard_editor($data, 'textfield', $textfieldoptions, $context,
'mod_somemodule', 'somearea', $data->id);</code>

Real world examples are in mod/glossary/edit.php and mod/glossary/comment.php

====Low level use====

When using editor element you need to preprocess and postprocess the data:
# detect if form was already submitted (usually means draft is area already exists) - ''file_get_submitted_draft_itemid()''
# prepare draft file area, temporary storage of all files attached to the text - ''file_prepare_draft_area()''
# convert encoded relative links to absolute links - ''file_prepare_draft_area()''
# create form and set current data
# after submission the changed files must be merged back into original area - ''file_save_draft_area_files()''
# absolute links have to be replaced by relative links - ''file_save_draft_area_files()''

=====Replace old htmleditor with editor=====

The file picker has been integrated with with TinyMCE to make the editor element. This new element should support all types on editors and should be able to switch them on-the-fly. Instances of the old htmleditor element in your forms should be replaced by the new editor element, this may need adding of new format and trusttext columns. For example:
<code php>
$mform->addElement('editor', 'entry', get_string('definition', 'glossary'), null,
array('maxfiles' => EDITOR_UNLIMITED_FILES));
</code>
The editor element can take following options: maxfiles, maxbytes, subdirs and changeformat. Please note that the embedded files is optional feature and is not expected be used everywhere.

'''Note''': the editor element now includes text format option. You should no longer use the separate format element type.

=====Prepare current data - text and files=====

<code php>
if (empty($entry->id)) {
$entry = new object();
$entry->id = null;
$entry->definition = '';
$entry->format = FORMAT_HTML;
}

$draftid_editor = file_get_submitted_draft_itemid('entry');
$currenttext = file_prepare_draft_area($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $entry->definition);
$entry->entry = array('text'=>$currenttext, 'format'=>$entry->format, 'itemid'=>$draftid_editor);

$mform->set_data($entry);
</code>

If there are multiple files, they will share the same itemid.

=====Obtain text, format and save draft files=====

To retrieve editor content, you need to use following code:

<code php>
if ($fromform = $mform->get_data()) {
// content of editor
$messagetext = $fromform->entry['text'];
// format of content
$messageformat = $fromform->entry['format'];
}
</code>

When a user selects a file using the file picker, the file is initially stored in a draft file area, and a URL is inserted into the HTML in the editor that lets the person editing the content (but no one else) see the file.

When the user submits the form, we then need to save the draft files to the correct place in permanent storage. (Just like you have to call $DB->update_record('tablename', $data); to have the other parts of the form submission stored correctly.)

The save_files_from_draft_area function and replace absolute links with internal relative links do:
<code php>
$messagetext = file_save_draft_area_files($draftid_editor, $context->id, 'mod_glossary', 'entry',
$entry->id, array('subdirs'=>true), $messagetext);
</code>
; $context->id, 'component', 'proper_file_area' and $entry->id : correspond to the contextid, filearea and itemid columns in the [[File_API#Table:_files|files table]].
; $messagetext : this is the message text. As the files are saved to the real file area, the URLs in this content are rewritten.

All URLs in content that point to files managed to the File API are converted to a form that starts '@@PLUGINFILE@@/' before the content is stored in the database. That is what we mean by rewriting.

== File serving==

=== Convert internal relative links to absolute links ===

Before text content is displayed to the user, any URLs in the '@@PLUGINFILE@@/' form in the content need to be rewritten to the real URL where the user can access the files.
<code php>
$messagetext = file_rewrite_pluginfile_urls($messagetext, 'pluginfile.php',
$context->id, 'mod_mymodule', 'proper_file_area', $itemid);
</code>
; $messagetext : is the content containing the @@PLUGINFILE@@ URLs from the database.
; 'pluginfile.php' : there are a number of different scripts that can serve files with different permissions checks. You need to specify which one to use.
; $context->id, 'mod_mymodule', 'proper_file_area', $itemid : uniquely identifies the file area, as before.

=== Implement file serving access control ===

Attachments and embedded images should have the same access control like the text itself, in majority of cases these files are served using pluginfile.php. Access control is defined in ''module/lib.php'' file in function ''module_pluginfile()''.

== File browsing support ==
Only owner of each file area is allowed to use low level File API function to access files, other parts of Moodle should use file browsing API.

Activities may specify browsing support in own module/lib.php file by implementing functions module_get_file_areas() and module_get_file_info().

== Upgrading your code ==
Here I will attempt to describe some simple steps you can take to upgrade your file-handling form elements from pre-2.0 code to 2.0. We will use the example of glossary, since it has been used above.

=== Preparing your options ===
Unless you are happy with the defaults, you will need to define an array of options for each file-handling form element. You could define it at different places, but it's best to put it in one place and make the array(s) available to other files if they need it. In the majority of cases, this will be in a file like edit.php

Previous code in mod/glossary/edit.php:
<code php>
$mform =& new mod_glossary_entry_form(null, compact('cm', 'glossary', 'hook', 'mode', 'e', 'context'));
</code>
New code:
<code php>
$maxbytes = $course->maxbytes;
// Could also use $CFG->maxbytes if you are not coding within a course context

$definitionoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes, 'trusttext'=>true,
'context'=>$context);
$attachmentoptions = array('subdirs'=>false, 'maxfiles'=>99, 'maxbytes'=>$maxbytes);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Note that the data being passed to the form constructor have changed also, but this is not part of the file API changes, I just include them to avoid confusion.

These options are for the htmleditor (definition field) and the filemanager (attachment field). They are used by a file called edit_form.php.

=== Element preparation ===
Before we look at this, however, we need to "prepare" the elements so that they can correctly display existing embedded images and attached files when you are editing a record instead of just creating one. So, let's take the code we've got so far in edit.php and add to it:

Currently upgraded code in edit.php:
<code php>
$mform = new mod_glossary_entry_form(null, array(
'current'=>$entry,
'cm'=>$cm,
'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
New code with element preparation:
<code php>
$entry = file_prepare_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_prepare_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
$mform = new mod_glossary_entry_form(null, array('current'=>$entry, 'cm'=>$cm, 'glossary'=>$glossary,
'definitionoptions'=>$definitionoptions,
'attachmentoptions'=>$attachmentoptions));
</code>
Things to note:
* $entry in this case is simply a stdClass object which may either represent a new glossary entry or an existing one.
* $entry->id must be the unique identifier for the current object. If we are creating a new entry, it will be null, but in all cases it must be defined.
* These two functions (file_prepare_standard_editor and file_prepare_standard_filemanager) are shortcuts functions that take care of some of the tedious setting up for you, but they make a couple of assumptions:
*# You '''must''' name the form element as {element}_editor or {element}_filemanager (see next section)
*# You '''must''' have at least the following fields in the database: {element} and {element}summary, as described earlier in this documentation

We can now look at the upgrades needed in the form definition file.

=== Form definition ===
Previous code in mod/glossary/edit_form.php:
<code php>
$mform->addElement('htmleditor', 'definition', get_string('definition', 'glossary'),
array('rows'=>20));
$mform->setType('definition', PARAM_RAW);
$mform->addRule('definition', null, 'required', null, 'client');
$mform->setHelpButton('definition', array('writing', 'richtext'), false, 'editorhelpbutton');
$mform->addElement('format');
// a bit further...
$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->setHelpButton('attachment', array('attachment', get_string('attachment', 'glossary'),
'glossary'));
</code>
New code:
<code php>
$definitionoptions = $this->_customdata['definitionoptions'];
$attachmentoptions = $this->_customdata['attachmentoptions'];
// a bit further...
$mform->addElement('editor', 'definition_editor', get_string('definition', 'glossary'), null,
$definitionoptions);
$mform->setType('definition_editor', PARAM_RAW);
$mform->addRule('definition_editor', get_string('required'), 'required', null, 'client');
// a bit further...
$mform->addElement('filemanager', 'attachment_filemanager', get_string('attachment', 'glossary'),
null, $attachmentoptions);
$mform->setHelpButton('attachment_filemanager', array('attachment2',
get_string('attachment', 'glossary'), 'glossary'));
</code>

Note the following:
* The format element and the help button are no longer required for the HTML editor element
* The name of the form element needs to be changed by adding '_editor' or '_manager' to the original name. This is a naming convention that is used by a couple of functions we will look at shortly
* Make sure $definitionoptions has context parameter, else system context is used and editor will not respect filter settings.

=== Handling submitted data ===
The final step is to handle the submitted data properly, i.e. retrieve the files and save them to disk, associating them with the record we have just created (a glossary entry in our example). This happens in edit.php:

Previous code in edit.php:
<code php>
// Section that updates an entry:
$todb->id = $e;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
$todb->attachment = $newfilename;
}

// Section that adds an entry:
if ($todb->id = insert_record("glossary_entries", $todb)) {
$e = $todb->id;
$dir = glossary_file_area_name($todb);
if ($mform->save_files($dir) and $newfilename = $mform->get_new_filename()) {
set_field("glossary_entries", "attachment", $newfilename, "id", $todb->id);
}
}
</code>
New code:
<code php>
// $todb was renamed to $entry, and the code was refactored
// so that the file-handling code is only used once for either an add or an update action.
// If an entry is being added, $DB->insert() has already been called, so we have a valid $entry->id
$entry = file_postupdate_standard_editor($entry, 'definition', $definitionoptions, $context,
'mod_glossary', 'entry', $entry->id);
$entry = file_postupdate_standard_filemanager($entry, 'attachment', $attachmentoptions, $context,
'mod_glossary', 'attachment', $entry->id);
// store the updated value values
$DB->update_record('glossary_entries', $entry);
</code>
Things to note:
* If you are adding a new record, you will still need to call update_record after calling the file_postupdate* functions

=== Gotchas ===
A few things to keep in mind:
* Make sure that you instantiate the moodle form before any call to $OUTPUT->header()

== See also ==

* [[File API]]
* [[Using the file API]]
* [[Repository plugins]]
* [[Portfolio API]]
* MDL-14589 - File API Meta issue
* [http://moodle.org/mod/forum/discuss.php?d=207748 Adding a text editor to a Moodle form]

[[Category:Files]]
[[Category:Repositories]]

Output Components

2016-10-04T12:34:15Z

Libertymoodle: /* Basic example - fix typ0 */

{{obsolete}}
See [[ Templates ]] for the recommended way to build pages in Moodle from Moodle 2.9.

{{ Moodle 2.0 }}

This page a list of Output Components for Moodle 2.0. It works closely with the Page API, so you may want to refer to that documentation as well.

== Components ==
Components in the Output API are classes that represent elements to be output. They do not contain any code for outputting anything, but they contain rich meta-data that is used by the Renderers to generate output. Some of the key aspects of components are outlined here:
* Components do not have defined constructors with arguments. Passing arguments to the default constructor will not do anything useful.
* Some components have a constructor which is used exclusively to instantiate object member variables.
* Components consist mainly of variables with sensible defaults, and a prepare() method which makes use of these variables to setup other defaults prior to rendering.
* The prepare() method always behaves the same way, regardless of which renderer is used. This ensures consistency of the component's variables.
* Additional "shortcut" methods are sometimes added to provide a more high-level API to developers.

=== moodle_html_component ===
*This is the base class for all output components. It is not declared as abstract, because you could actually use it to instantiate a basic component. However, almost all rendering functions will expect a sub-class of this class as a parameter, so instantiating it is unlikely to be very useful.
*This class basically holds data and useful functions that can apply to any component, such as id, classes, style, alt and title (HTML attributes valid for any XHTML element). It also handles the collection and setting up of component_actions, which are described below. Refer to the class' PHP docs for details on variables and functions.
*This class also defines a function for generating unique HTML ids for components that require one, and holds a static array for generated ids to prevent duplication.
*A set_label($text, $for=null) is defined, with the first argument accepting either a string or a html_label component, in which latter case the second argument is ignored. If the component does not have an $id value, one will be generated and assigned to the label's $for value unless a html_label object is given as the $text argument. For this reason, if you explicitly set a component's $id value, make sure set_label() is called after you set that value.

=== HTML low-level components ===
This list of components replicate basic HTML elements. They are prefixed with html_ to make it clear that they are the basic building blocks of the output API.

==== html_label ====
*Many HTML elements may have a label (input fields, dropdowns etc.). Some rendering functions look for this label and render it accordingly.
*html_label requires a $text value, and should be given a $for value for accessibility reasons. It is rendered ultimately by $OUTPUT->label(html_label $label).

==== html_field ====
*Represents a HTML input field. Can be used to output any input type, although some of its variables only apply to some types (e.g. maxlength only applies to text inputs).
*It has a shortcut method for preparing a text input: make_text($name, $value, $alt, $maxlength).

==== html_button ====
*Represents a HTML button, which may be rendered in many different ways, though by default it is rendered as an input field of type "button".
*Requires a $text value (by default used as the HTML "value" attribute)

==== action_link ====
*Represents a link, by default rendered by the $OUTPUT->link() function as HTML:
<code html4strict>
<a href="$url">$text</a>
</code>

==== html_image ====
*Simple class representing an image, rendered by $OUTPUT->image().
*The $alt variable is set to HTML_ATTR_EMPTY by default. This constant is interpreted by the renderer as an attribute with an empty string as a value. If you use an actual empty string, the attribute will not be output at all, which would break XHTML strict for the <img/> tag.

==== html_form ====
*This component represents a form 'wrapper' with an optional html_button object. You can use $OUTPUT->form($form, $contents) to output a form with any HTML you want within it.
*The object requires a $url value, which can either be a string or a moodle_url object. In the prepare() method, this variable will be converted to a moodle_url.
*If the $method "post" is used, the sesskey param will be added automatically
*You can use the $params array to specify hidden inputs, but it will be ignored if you give a moodle_url as the $url value (because moodle_urls include query params).
*This object is also used by the $OUTPUT->button($formwithbutton) and the $OUTPUT->confirm($message, $formcontinue, $formcancel) methods.

==== html_list ====
*Represents a HTML nested list.
*Has a load_data($tree, $level=0) recursive method which take a nested array and stores instantiated html_list_item objects in the $items array.
*CSS classes are automatically added to each element in the list, to allow for custom styling.
*This is rendered by $OUTPUT->htmllist($list) as a <nowiki><ul> or <ol></nowiki> element, but could be used to output nav menus etc. by yet unwritten output methods.
*Use the $type variable to specify if the list should be ordered or unordered.

==== html_list_item ====
*Represents a list item used by the html_list component. Only has a $value variable, but also benefits from all other variables and methods of the moodle_html_component base class.

==== html_table ====
*Represents a HTML table with data
*Is intended to replace the old flexible_table class
*The $data array either holds an associate array of arrays representing rows and cells, or it can be set up with html_table_row and html_table_cell objects, for finer control over the look and layout of the table cells.
*In the html_writer::table($table) method, the $data array's contents are converted into html_table_row and html_table_cell objects if they are not already of that type.

==== html_table_row ====
*A simple component holding an array of html_table_cell objects.

==== html_table_cell ====
*This represents a table cell, and is aggregated by a html_table_row object, itself aggregated by html_table.
*This component's variables mirror those of the XHTML <nowiki><td> or <th></nowiki> elements (differentiated by the $header boolean)

==== html_select ====
*This object is by far the most complex HTML component in Moodle. It represents any element that presents the user with a choice. This includes:
*#A dropdown menu (<nowiki><select> tag</nowiki>), optionally with automatic redirection upon selection of an option
*#A set of radio buttons (<nowiki><input type="radio" /> tag</nowiki>)
*#A set of checkboxes (<nowiki><input type="checkbox" /> tag</nowiki>)
*However, remember that the HTML tags given above are the default rendering of a html_select object. This object can hold so much data that it could be rendered in a multiple of different ways, not necessarily using these traditional HTML tags.
*This class has a special method initialise_options() which converts the given $options into html_select_optgroup and html_select_option objects. This allows you to override these options' defaults and add style, classes and component_action objects before the object is sent to the renderer.

*Some examples follow:

===== Basic example =====
The following will output a basic drop-down menu, ready to be included in a form:
<code php>
$select = html_select::make(array('1' => 'Value 1', '2' => 'Value 2'), 'choice1', '2');
echo $OUTPUT->select($select);
</code>
Outputs:
<code html4strict>
<select id="menuchoice1" class="menuchoice1 select" name="choice1">
<option value="0">Choose...</option>
<option value="1">Value 1</option>
<option selected="selected" value="2">Value 2</option>
</select>
</code>
Note that a default "Choose..." option with a value of 0 is added to the menu. To remove this, follow the next example:
<code php>
$select->nothinglabel = false;
</code>
This will remove the default option completely.

===== Nested menus =====
You can also render a menu with one level of nesting, rendered as a dropdown with optgroups. You just need to do two things to achieve that:
#Specify $select->nested = true
#Either:
#*$select->load_data($flatarray), which requires a rather cryptic syntax with double-dashes for optgroups
#*$select->load_data($nestedarray), the first level's keys are the names of the optgroups, their arrays are the options' value=>label pairs.
#*Prepare the data directly as html_select_optgroup and html_select_option objects. This method requires more code but less debugging because it is a lot less brittle than a string-based syntax, and it allows more customised classes, JS actions etc. on each individual option.

The preferred method is the second one in the majority of cases, because it is easy to setup and debug. The first method should be avoided and will not be demonstrated here.

<code php>
// Method 2:
$options = array('Group1' => array('value1' => 'Option 1', 'value2' => 'Option 2'), 'Group2' => array('value3' => 'Option 3', 'value4' => 'Option 4'));
$select = html_select::make($options, 'choice1', 'value1');
$select->nested = true;
echo $OUTPUT->select($select);

// Method 3:
$optgroup1 = new html_select_optgroup();
$optgroup2 = new html_select_optgroup();
$optgroup1->text = 'Group1';
$optgroup2->text = 'Group2';

$option1 = new html_select_option();
$option2 = new html_select_option();
$option3 = new html_select_option();
$option4 = new html_select_option();

$option1->text = 'Option 1';
$option1->value = 'value1';
$option2->text = 'Option 2';
$option2->value = 'value2';
$option3->text = 'Option 3';
$option3->value = 'value3';
$option4->text = 'Option 4';
$option4->value = 'value4';

$optgroup1->options = array($option1, $option2);
$optgroup2->options = array($option3, $option4);

$select = html_select::make(array($optgroup1, $optgroup2), 'choice1', 'value1');
$select->nested = true;
echo $OUTPUT->select($select);
</code>
Both these methods Output:
<code html4strict>
<select id="menuchoice1" class="menuchoice1 select" name="choice1">
<optgroup label="Group1">
<option selected="selected" value="value1">Option 1</option>
<option value="value2">Option 2</option>
</optgroup>
<optgroup label="Group2">
<option value="value3">Option 3</option>
<option value="value4">Option 4</option>
</optgroup>
</select>
</code>
Although the last method looks very code-intensive, most of it would obviously be reduced using foreach loops, and it allows for much more customisation of the components.

===== Yes/No menu =====
A common use case is to print a Yes/No menu. This could be output as two radio buttons, but it is sometimes output as a menu. The two cases are demonstrated here:
<code php>
$select = html_select::make_yes_no('choice1', 1);
$select->nothinglabel = false; // Don't forget to do this, or the "Choose..." option will appear and have the same value as the "No" option!
echo $OUTPUT->select($select);
</code>
Outputs:
<code html4strict>
<select id="menuchoice1" class="menuchoice1 select" name="choice1">
<option value="0">No</option>
<option selected="selected" value="1">Yes</option>
</select>
</code>

Radio buttons:
<code php>
$select->rendertype = 'radio';
echo $OUTPUT->select($select);
</code>
<code html4strict>
Outputs:
<span class="radiogroup choice1 rb0">
<label for="html_select_option-b4d4bd">No</label>
<input id="html_select_option-b4d4bd" type="radio" name="choice1" value="0"/>
</span>
<span class="radiogroup choice1 rb1">
<label for="html_select_option-1eaa39">Yes</label>
<input id="html_select_option-1eaa39" type="radio" checked="checked" name="choice1" value="1"/>
</span>
</code>

However, in many cases it is better to display a yes/no choice as a single checkbox. For this purpose, it is better to instantiate a single html_option object and pass it to $OUTPUT->checkbox().

===== Date/Time selectors =====
NOTE: This part of the API is under review

The html_select object can be used to output date or time selectors. A shortcut method is provided for this purpose: make_time_selector($type, $currenttime, $step);
For more concise code, you can use the higher-level method make_time_selectors($selectors, $currentime, $step);

<code php>
$dayselector = html_select::make_time_selector('days', 'myday', '120308000');
$monthselector = html_select::make_time_selector('months', 'mymonth', '120308000');
$yearselector = html_select::make_time_selector('years', 'myyear', '120308000');
$hourselector = html_select::make_time_selector('hours', 'myhour', '120308000');
$minuteselector = html_select::make_time_selector('minutes', 'myminute', '120308000', 5);
echo $OUTPUT->select($dayselector);
echo $OUTPUT->select($monthselector);
echo $OUTPUT->select($yearselector);
echo $OUTPUT->select($hourselector);
echo $OUTPUT->select($minuteselector);

// OR
$selectors = html_select::make_time_selectors(array('days' => 'myday', 'months' => 'mymonth', 'years' => 'myyear', 'hours' => 'myhour', 'minutes' => 'myminute'), '120308000', 5);
foreach ($selectors as $select) {
echo $OUTPUT->select($select);
}
</code>
Outputs:
[[Image:timeselectors.png]]

===== Popup Forms =====
*This is a really bad name for a dropdown menu that redirects the user when an option is selected.
*html_select::make_popup_form() is a shortcut method for returning an object ready for rendering through $OUTPUT->select()
*The basic premise of a "popup form" is that each option has as its value the URL to which the user should be redirected when that option is selected
*To simplify this process, make_popup_form() takes a URL as its first argument, and the name of a query param as the second. It is expected that the option values represent the value that will be assigned to this "variable" parameter.

<code php>
$options = array(1 => 'Page 1', 2 => 'Page 2', 3 => 'Page 3');
$select = html_select::make_popup_form('http://domain.com/index.php', 'id', $options, 'myform');
echo $OUTPUT->select($select);
</code>
Outputs:
<code html4strict>
<form id="myform" class="popupform" action="http://enterprise/cvs_moodle_head/course/jumpto.php" method="get">
<div>
<input type="hidden" value="JEgniUhzzx" name="sesskey"/>
<select id="myform_jump" class="menujump select" name="jump">
<option value="0">Choose...</option>
<option value="http://domain.com/index.php?id=1">Page 1</option>
<option value="http://domain.com/index.php?id=2">Page 2</option>
<option value="http://domain.com/index.php?id=3">Page 3</option>
</select>
<div id="noscriptmyform" style="display: none;">
<input class="singlebutton" type="submit" value="Go"/>
</div>
</div>
</form>
</code>

Sometimes you will need some of the URLs to have a different base, or to have more parameters that change between options. The best way to achieve this is demonstrated here:

<code php>
$options = array('http://domain.com/index.php?id=1' => 'Page 1',
'http://domain.com/otherpage/index.php?modid=1' => 'Page 2',
'http://domain.com/index.php?id=1&othervar=2' => 'Page 3');
$select = html_select::make_popup_form('', '', $options, 'myform');
$select->override_option_values($options);
echo $OUTPUT->select($select);
</code>
Outputs:
<code html4strict>
<form id="myform" class="popupform" action="http://enterprise/cvs_moodle_head/course/jumpto.php" method="get">
<div>
<input type="hidden" value="JEgniUhzzx" name="sesskey"/>
<select id="myform_jump" class="menujump select" name="jump">
<option value="0">Choose...</option>
<option value="http://domain.com/index.php?id=1">Page 1</option>
<option value="http://domain.com/otherpage/index.php?modid=1">Page 2</option>
<option value="http://domain.com/index.php?id=1&othervar=2">Page 3</option>
</select>
<div id="noscriptmyform" style="display: none;">
<input class="singlebutton" type="submit" value="Go"/>
</div>
</div>
</form>
</code>

==== html_select_option ====
*This component represents an option
*It is not necessarily rendered as an <nowiki><option></nowiki> tag, but can also be rendered as a radio or a checkbox
*It can be aggregated by html_select and html_select_optgroup, or used by itself in $OUTPUT->checkbox($option, $name)
*It has a shortcut method for preparing a checkbox for output: make_checkbox($value, $selected, $label, $alt);

<code php>
$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
echo $OUTPUT->checkbox($checkbox, 'donotask');
</code>
Outputs:
<code html4strict>
<span class="checkbox donotask">
<input id="html_select_option-e7be90" type="checkbox" name="donotask" value="1"/>
<label for="html_select_option-e7be90">Do Not Ask</label>
</span>
</code>
*Note that an ID is generated in this case even though no component_action was added. This is the default behaviour for the checkbox() method.

==== html_select_optgroup ====
*This represents an option group, used only by html_select to group options together. It doesn't do anything particularly useful in itself apart from aggregating html_select_option objects and having a text value.
*It benefits from all the moodle_html_component variables and methods.

=== Moodle components ===
The following components do not map exactly to HTML elements, so they are prefixed with moodle_.

==== moodle_paging_bar ====
*Represents a paging bar used to navigate a large list of records like users, forum posts etc.
*Since 4 parameters are required, a shortcut function is provided: moodle_paging_bar::make($totalcount, $page, $perpage, $baseurl)
*The first page has a value of 0 but is displayed as 1, so remember this offset.
*If you have multiple paging bars on one page for different lists, set the $pagevar variable
*See [[Output_API#paging_bar]] for example usage and output

==== moodle_user_picture ====
*Represents a user's picture to be output through $OUTPUT->user_picture()
*Requires at least a $user object of stdClass with a minimum of data (id) and a $courseid
*If no specific image is given (as a html_image object), then the default image is loaded
*See [[Output_API#user_picture]] for example usage and output

==== moodle_action_icon ====
*Simply put, this is a linked image.
*See [[Output_API#action_icon]] for example usage and output

==== moodle_help_icon ====
See [[Output_API#help_icon]] For example usage. Replaces the old helpbutton() global function.

== Renderers ==
=== renderer_base ===
* Simple base class for Moodle renderers.
* Tracks the xhtml_container_stack to use, which is passed in in the constructor.
* Also has methods to facilitate generating HTML output.

==== output_tag methods ====
* Low-level functions for outputting specific HTML tags.
* For empty tags (with no content), use output_empty_tag

==== pix_url ====
* Same as old_icon_url, but for old module icons
* The equivalent for "$CFG->modpixpath/$mod/icon.gif" is mod_icon_url('icon', $mod)

==== prepare_event_handlers(&$component) ====
* Used by rendering functions to prepare JS event listeners for components that may require it.
* All components that can receive user input should go through this method

==== prepare_legacy_width_and_height($component) ====
* Returns the correct CSS for components that have the deprecated $height and/or $width attributes

=== core_renderer ===
Since these functions are very well documented inline (phpdoc), I will only put examples here, without in-depth explanations.

==== action_icon ====
<code php>
$icon = new moodle_action_icon();
$icon->image->src = $OUTPUT->old_icon_url('moodlelogo');
$icon->image->alt = 'What is moodle?';
$icon->link->url = new moodle_url('http://domain.com/index.php');
$icon->add_confirm_action('Are you sure?'); // Optional. Equivalent to doing $icon->link->add_confirm_action('Are you sure?');
echo $OUTPUT->action_icon($icon);
</code>
Outputs:
<code html4strict>
<a id="html_link-2b4310" href="http://domain.com/index.php">
<img class="action-icon image" alt="What is moodle?" src="http://enterprise/cvs_moodle_head/pix/moodlelogo.gif"/>
</a>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_link-2b4310', 'click', confirm_dialog, {"message":"Are you sure?"});
//]]>
</script>
</code>

==== box, box_start and box_end ====
<code php>
echo $OUTPUT->box('A message of some kind');
// OR
echo $OUTPUT->box_start();
echo 'A message of some kind';
echo $OUTPUT->box_end();
</code>
Outputs:
<code html4strict>
<div class="box generalbox">A message of some kind</div>
</code>

==== button ====
*Be aware that this method's signature requires a html_form component as its only argument. This form object must have a $button value (html_button)
<code php>
$form = new html_form();
$form->url = new moodle_url('http://domain.com/index.php', array('id' => 3, 'userid' => 5));
$form->button->text = 'My account';
echo $OUTPUT->button($form);
</code>
Outputs:
<code html4strict>
<div class="singlebutton">
<form action="http://domain.com/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input type="hidden" value="3" name="id"/>
<input type="hidden" value="5" name="userid"/>
<input class="singlebutton" type="submit" value="My account"/>
</div>
</form>
</div>
</code>

==== checkbox ====
<code php>
$checkbox = html_select_option::make_checkbox('1', false, get_string('donotask'));
echo $OUTPUT->checkbox($checkbox, 'donotask');
</code>
Outputs:
<code html4strict>
<span class="checkbox donotask">
<input id="html_select_option-e7be90" type="checkbox" name="donotask" value="1"/>
<label for="html_select_option-e7be90">Do Not Ask</label>
</span>
</code>

==== close_window_button ====
<code php>
echo $OUTPUT->close_window_button();
</code>
Outputs:
<code html4strict>
<div class="closewindow">
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/#" method="get">
<div>
<input id="html_button-d35ffa" class="singlebutton" type="submit" value="Close this window"/>
</div>
</form>
</div>
</div>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_button-d35ffa', 'click', close_window);
//]]>
</script>
</code>

==== confirm ====
<code php>
echo $OUTPUT->confirm('Are you sure?', '/index.php?delete=1', '/index.php');
</code>
Outputs
<code html4strict>
<div id="notice" class="box generalbox">
<p>Are you sure?</p>
<div class="buttons">
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input type="hidden" value="1" name="delete"/>
<input class="singlebutton" type="submit" value="Yes"/>
</div>
</form>
</div>
<div class="singlebutton">
<form action="http://enterprise/cvs_moodle_head/index.php" method="post">
<div>
<input type="hidden" value="fXlccUgFTz" name="sesskey"/>
<input class="singlebutton" type="submit" value="No"/>
</div>
</form>
</div>
</div>
</div>
</code>

==== container, container_start and container_end ====
*Container differs from box in two ways:
*#It doesn't add default CSS classes (box adds a "box" class and a "generalbox" class unless the default is overridden)
*#It is stored in the XHTML stack as a "container", not a "box"
<code php>
echo $OUTPUT->container('A message of some kind', 'important', 'notice');
// OR
echo $OUTPUT->container_start('important', 'notice');
echo 'A message of some kind';
echo $OUTPUT->container_end();
</code>
Outputs:
<code html4strict>
<div id="notice" class="important">A message of some kind</div>
</code>

==== continue_button ====
<code php>
echo $OUTPUT->continue_button('http://domain.com/index.php?id=2&userid=4');
// OR (preferred)
echo $OUTPUT->continue_button(new moodle_url('http://domain.com/index.php', array('id' => 2, 'userid' => 4)));
</code>
Outputs:
<code html4strict>
<div class="continuebutton">
<div class="singlebutton">
<form action="http://domain.com/index.php" method="get">
<div>
<input type="hidden" value="2" name="id"/>
<input type="hidden" value="4" name="userid"/>
<input class="singlebutton" type="submit" value="Continue"/>
</div>
</form>
</div>
</div>
</code>

==== doc_link ====
Not for general use.

==== error_text ====
<code php>
echo $OUTPUT->error_text("It's all broken!");
</code>
Outputs:
<code html4strict>
<span class="error">It's all broken!</span>
</code>

==== footer ====
*Simply call $OUTPUT->footer() at the end of each page.
*The output may vary depending on which page you are on.

==== form ====
<code php>
$form = new html_form();
$form->url = new moodle_url('http://domain.com/index.php', array('id' => 3, 'userid' => 5));
$checkbox = html_select_option::make_checkbox(1, false, 'Agree to terms');
$contents = $OUTPUT->container('Terms and conditions: Be kind and courteous');
$contents .= $OUTPUT->checkbox($checkbox, 'agree');
echo $OUTPUT->form($form, $contents);
</code>
Outputs:
<code html4strict>
<form action="http://domain.com/index.php" method="post">
<div>
<input type="hidden" value="79D3tSzYfz" name="sesskey"/>
<input type="hidden" value="3" name="id"/>
<input type="hidden" value="5" name="userid"/>
<div>Terms and conditions: Be kind and courteous</div>
<span class="checkbox agree">
<input id="html_select_option-3a3de0" type="checkbox" name="agree" value="1"/>
<label for="html_select_option-3a3de0">Agree to terms</label>
</span>
<input class="singlebutton" type="submit" value="Submit"/>
</div>
</form>
</code>

==== header ====
==== heading ====
<code php>
echo $OUTPUT->heading(get_string('help'), 3, 'helptitle', 'uniqueid');
</code>
Outputs:
<code html4strict>
<h3 id="uniqueid" class="helptitle">Help</h3>
</code>

==== heading_with_help ====
<code php>
$helpicon = new moodle_help_icon();
$helpicon->page = 'posts';
$helpicon->text = 'Help about forum posts';
$helpicon->module = 'forum';
echo $OUTPUT->heading_with_help($helpicon);
</code>
Outputs:
<code html4strict>
<div class="heading-with-help">
<h2 class="main help">Help about forum posts</h2>
<span class="helplink">
<a id="html_link-7b0b0d" href="http://enterprise/cvs_moodle_head/help.php?module=forum&file=posts.html">
<img class="iconhelp image" src="http://enterprise/cvs_moodle_head/pix/help.gif" alt="" />
</a>
</span>
</div>
</code>

==== help_icon ====
<code php>
$helpicon = new moodle_help_icon();
$helpicon->page = 'posts';
$helpicon->text = 'Help about forum posts';
$helpicon->module = 'forum';
echo $OUTPUT->help_icon($helpicon);
</code>
Outputs:
<code html4strict>
<span class="helplink">
<a id="html_link-42560f" href="http://enterprise/cvs_moodle_head/help.php?module=forum&file=posts.html">
<img class="iconhelp image" src="http://enterprise/cvs_moodle_head/pix/help.gif" alt="Help about forum posts" title="Help about forum posts" />
</a>
</span>
</code>

==== htmllist ====
Warning - The html_list class and the $OUTPUT->htmllist methods do not exist!
Unlike other things on this page the below example will not work.

<code php>
$data = array('Group 1' => array('Group 1.1' => array('Item 1.1.1', 'Item 1.1.2'), 'Item 1.2'),
'Group 2' => array('Item 2.1', 'Item 2.2', 'Item 2.3'));
$list = new html_list();
$list->type = 'ordered';
$list->load_data($data);
echo $OUTPUT->htmllist($list);
</code>
Outputs:
<code html4strict>
<ol class="list-0">
<li>Group 1
<ol class="list-1">
<li>Group 1.1
<ol class="list-2">
<li class="list-item-2-1">Item 1.1.1</li>
<li class="list-item-2-2">Item 1.1.2</li>
</ol>
</li>
<li class="list-item-1-2">Item 1.2</li>
</ol>
</li>
<li>Group 2
<ol class="list-1">
<li class="list-item-1-1">Item 2.1</li>
<li class="list-item-1-2">Item 2.2</li>
<li class="list-item-1-3">Item 2.3</li>
</ol>
</li>
</ol>
</code>
Notes:
*The class names are generated automatically. For ol and ul classes, the digit represents the depth of nesting.
*This is also the meaning of the first digit in the list item classes, the second being the number of the list item in the item's list.
*Once you have called $list->load_data($array), the list->items array is filled with html_list and html_list_item components, which you can setup in more details in preparation for output.

==== image ====
<code php>
$image = new html_image();
$image->src = 'http://domain.com/help.gif';
$image->alt = 'Helpful icon';
$image->width = 24;
$image->height = 24;
</code>
Outputs:
<code html4strict>
<img class="image" style="height: 24px; width: 24px;" alt="Helpful icon" src="http://domain.com/help.gif"/>
</code>

==== label ====
<code php>
$label = new html_label();
$label->text = 'Form element';
echo $OUTPUT->label($label);
</code>
Outputs:
<code html4strict>
<label>Form element</label>
</code>

This is a rather low-level function, you will rarely need to call it directly. Instead, use labels on subclasses of labelled_html_component:

<code php>
$field = new html_field();
$field->name = 'variable1';
$field->id = 'myfield';
$field->set_label('Form element');
echo $OUTPUT->textfield($field);
</code>
Outputs:
<code html4strict>
<span class="textfield variable1">
<label for="myfield">Form element</label>
<input id="myfield" type="text" style="width: 4em;" name="variable1"/>
</span>
</code>

==== link ====
<code php>
$link = new action_link();
$link->url = new moodle_url('http://domain.com/index.php', array('id' => 2, 'action' => 'browse')); // required, but you can use a string instead
$link->text = 'Browse page 2'; // Required
echo $OUTPUT->link($link)
</code>
Outputs:
<code html4strict>
<a href="http://domain.com/index.php?id=2&action=browse">Browse page 2</a>
</code>

==== link_to_popup ====
*Same API as for link(), but you set a popup_action on the component, and link() will forward it to the link_to_popup() method. You shouldn't need to call this method directly.
==== link ====
<code php>
$link = html_link::make(new moodle_url('http://domain.com/index.php', array('id' => 2, 'action' => 'browse')), 'Browse page 2');
$link->add_action(new popup_action('click', $link->url));
echo $OUTPUT->link($link)
</code>
Outputs:
<code html4strict>
<a id="html_link-985165" href="http://domain.com/index.php?id=2&action=browse">Browse page 2</a>
...
<script type="text/javascript">
//<![CDATA[
YAHOO.util.Event.addListener('html_link-985165', 'click', openpopup, {"url":"http:\/\/domain.com\/index.php?id=2&action=browse","name":"popup","options":"[...]"});
//]]>
</script>
</code>

==== notification ====
*By default this function works just like container(), with a default class set to 'notifyproblem'.
*It actually inserts a template token which is interpreted and rendered at a later stage.

==== paging_bar ====
<code php>
$pagingbar = moodle_paging_bar::make(120, 3, 20, 'http://domain.com/index.php');
// Optionally : $pagingbar->pagevar = 'mypage';
echo $OUTPUT->paging_bar($pagingbar);
</code>
Outputs:
<code html4strict>
<div class="paging">
Page: (
<a class="previous" href="http://domain.com/index.php?page=2">Previous</a>
)
<a href="http://domain.com/index.php?page=0">1</a>
<a href="http://domain.com/index.php?page=1">2</a>
<a href="http://domain.com/index.php?page=2">3</a>
4
<a href="http://domain.com/index.php?page=4">5</a>
<a href="http://domain.com/index.php?page=5">6</a>
(
<a class="next" href="http://domain.com/index.php?page=4">Next</a>
)
</div>
</code>

==== radio ====
==== select ====
*This method depends heavily on how the passed component is configured, so see [[Output_API#html_select]] For a detailed description

==== select_option ====
*Used internally by select(), you shouldn't need to call this directly.

==== spacer ====
==== table ====
<code php>
$table = new html_table();
$table->head = array('Student', 'Grade', 'Comments');
$table->data = array(
array('Harry Potter', '76%', 'Getting better'),
array('Rincewind', '89%', 'Lucky as usual'),
array('Elminster Aumar', '100%', 'Easy when you know everything!')
);
echo html_writer::table($table);
</code>
Outputs:
<code html4strict>
<table class="generaltable">
<thead>
<tr>
<th class="header c0" scope="col" style="white-space: nowrap;">Student</th>
<th class="header c1" scope="col" style="white-space: nowrap;">Grade</th>
<th class="header c2 lastcol" scope="col" style="white-space: nowrap;">Comments</th>
</tr>
</thead>
<tbody>
<tr class="r0">
<td class="cell">Harry Potter</td>
<td class="cell">76%</td>
<td class="cell">Getting better</td>
</tr>
<tr class="r1">
<td class="cell">Rincewind</td>
<td class="cell">89%</td>
<td class="cell">Lucky as usual</td>
</tr>
<tr class="r0 lastrow">
<td class="cell">Elminster Aumar</td>
<td class="cell">100%</td>
<td class="cell">Easy when you know everything!</td>
</tr>
</tbody>
</table>
</code>

==== textfield ====
==== user_picture ====
<code php>
$user = new stdClass();
$user->id = 1;
$userpic = new moodle_user_picture();
$userpic->user = $user;
$userpic->courseid = 1;

echo $OUTPUT->user_picture($userpic);
</code>
Outputs:
<code html4strict>
<img class="image" style="height: 35px; width: 35px;" alt="Picture of Admin User" src="http://enterprise/cvs_moodle_head/pix/u/f2.png"/>
</code>

=== cli_core_renderer ===

== Actions ==
*Component actions are objects that represent Moodle's response to a user's action on a component.
*These objects bind to a moodle_html_component or one of its subclasses.
*The renderers are responsible for interpreting these actions and generating the appropriate Javascript code.

=== component_action ===
*This is the base class for all component actions. It includes the name of the event (click, change, keydown etc.), the name of the Javascript function to be called, and an optional array of arguments to pass to the JS function.
*'''Important!''': the JS function called by this event handler will always receive two arguments: "event" and "args".
**The first is a DOM event object and can be used within the function to get the element on which the action was performed, and get information about the event (such as which key was pressed).
**The second argument (args) is an object with named parameters (a "hash") that includes the optional JS arguments you defined in the component_action instantiation.
*Any component which receives an action (through the moodle_html_component::add_action($action) method) needs to be given a unique DOM id attribute. If you do not specify it, one will be automatically generated for you.
<code php>
$link = new action_link();
$link->url = new moodle_url('/index.php', array('id' => 2, 'delete' => 5));
$link->text = 'Delete this website';

$link->add_action('click', 'confirm_dialog', array('message' => 'Are you sure?'));
// OR
$action = new component_action('click', 'confirm_dialog', array('message' => 'Are you REALLY sure?'));
$link->add_action($action);

echo $OUTPUT->link($link);
</code>
*Actions cannot yet be stacked in a component. This means that the above code will behave erratically because we are setting two actions for the same event. It is better to write a custom, more complex JS function than to try to bind several event handlers to the same component.

=== popup_action ===
*This action opens up a new window using the given $url value.
*It has a $params associative array with the arguments to the JS window.open() function. It has sensible defaults, but you can override them if necessary.

== Factories ==

== Theme Config ==

== XHTML Container Stack ==

== Miscellaneous functions ==

==See also==
* [[Templates]]
* [[How_Moodle_outputs_HTML]]
* [[Migrating your code to the 2.0 rendering_API]]
* [[Outputting HTML in 2.0]]
* [[Theme_changes]]

AJAX

2016-10-04T07:06:14Z

Libertymoodle: /* Add Internet Archive link to 404 articles */

'''AJAX (Asynchronous Javascript and XML)''' is a modern web design technique that allows for more interactivity by making webpages that fetch data in the background and alter themselves without reloading the entire page. This helps to make a page feel much more like an application than a web page. AJAX is a new way of working with existing technologies (including HTML, [[Javascript]], [[CSS]] and the ''XMLHttpRequest object'' amongst others) rather than a new piece of technology in itself.

Although AJAX indicates that XML is used, the term really relates to the group of technologies and in Moodle we tend to favour use of JSON rather than XML as the syntax is lighter and leads to a smaller output. It is also easier to construct from php data structures.

== Ajax in Moodle ==
{{ Moodle 2.9 }}

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions.

Some benefits of this system are:
# No new ajax scripts need auditing for security vulnerabilities
# Multiple requests can be chained in a single http request
# Strict type checking for all parameters and return types
# New webservice functions benefit Ajax interfaces and web service clients

So the steps required to create an ajax interaction are:

# Write or find an existing web service function to handle the ajax interaction: See [[ Web_services ]]
# White list the web service for ajax. To do this, you can define 'ajax' => true in your function's definition, in db/services.php. Only functions that are whitelisted using this mechanism will be available to the ajax script.
# Call the web service from javascript in response to a user action:

Example calling core_get_string:
<code javascript>
require(['core/ajax'], function(ajax) {
var promises = ajax.call([
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'pluginname' } },
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'changerate' } }
]);

promises[0].done(function(response) {
console.log('mod_wiki/pluginname is' + response);
}).fail(function(ex) {
// do something with the exception
});

promises[1].done(function(response) {
console.log('mod_wiki/changerate is' + response);
}).fail(function(ex) {
// do something with the exception
});
});
</code>

Note: This example chains to separate calls to the core_get_string webservice in one http request

Note: Don't actually fetch strings like this, it is just an example, use the 'core/str' module instead.

To update parts of the UI in response to Ajax changes, consider using [[ Templates ]]

For information on writing AJAX scripts for Moodle before Moodle 2.9 see: [[ AJAX pre 2.9 ]]

Watch a video about using templates with webservices and AJAX in Moodle: https://www.youtube.com/watch?v=UTePjRZqAg8

Tricky things to know about using webservices with ajax calls:
# Any call to $PAGE->get_renderer() requires the correct theme be set. If this is done in a webservice - it is likely that the theme needs to be a parameter to the webservice.
# Text returned from a webservice must be properly filtered. This means it must go through external_format_text or external_format_string (since 3.0 - see MDL-51213) with the correct context.
# The correct context for 2 is the most specific context relating to the thing being output e.g. for a user's profile desciption the context is the user context.
# After adding any dynamic content to a page, Moodle's filters need to be notified via M.core.event.FILTER_CONTENT_UPDATED (MDL-51222 makes this easier)

In some very rare cases - you can mark webservices as safe to call without a session. These should only be used for webservices that return 100% public information and do not consume many resources. A current example is core_get_string. To mark a webservice as safe to call without a session you need to do 2 things.
# Add 'loginrequired' => false to the service definition in db/services.php
# Pass "false" as the 3rd argument to the ajax "call" method when calling the webservice.
The benefit to marking these safe webservice is that (a) they can be called from the login page before we have a session and (b) they will perform faster because they will bypass moodles session code when responding to the webservice call.

== See also ==

* [[ AJAX pre 2.9 ]]
* [[Templates]]
* [[Javascript Modules]]
* [[Javascript FAQ]]
* [[Javascript]]
* [[Firebug#Debugging_AJAX_with_Firebug|Debugging AJAX with Firebug]]

* [http://www.adaptivepath.com/publications/essays/archives/000385.php ''Ajax: A New Approach to Web Applications'', the original Ajax article by Adaptive Path] (This link is now dead, but the article is preserved on the [https://web.archive.org/web/20070225140912/http://www.adaptivepath.com/publications/essays/archives/000385.php Internet Archive])
* [http://developer.mozilla.org/en/docs/AJAX:Getting_Started ''AJAX: Getting Started'' article on developer.mozilla.org]
* [http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html ''10 places you must use AJAX'' by Adam Bosworth] (Also a dead link... [https://web.archive.org/web/20060127015713/http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html Internet Archive copy])
* [http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype ''Considering Ajax, Part 1: Cut through the hype'' from IBM developerworks] (Also a dead link... [https://web.archive.org/web/20080602101238/http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype Internet Archive copy])
* [http://en.wikipedia.org/wiki/Ajax_%28programming%29 Wikipedia article on ''AJAX'']
* [http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ How to Make Your AJAX Applications Accessible: 40 Tutorials and Articles] (Also a dead link... [https://web.archive.org/web/20090225094656/http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ Internet Archive copy])
*[http://www.ajaxload.info/ AJAX loading icon generator]

[[Category:Javascript]]
[[Category:AJAX]]

AJAX

2016-10-04T06:43:25Z

Libertymoodle: /* Add Internet Archive link to 404 article */

'''AJAX (Asynchronous Javascript and XML)''' is a modern web design technique that allows for more interactivity by making webpages that fetch data in the background and alter themselves without reloading the entire page. This helps to make a page feel much more like an application than a web page. AJAX is a new way of working with existing technologies (including HTML, [[Javascript]], [[CSS]] and the ''XMLHttpRequest object'' amongst others) rather than a new piece of technology in itself.

Although AJAX indicates that XML is used, the term really relates to the group of technologies and in Moodle we tend to favour use of JSON rather than XML as the syntax is lighter and leads to a smaller output. It is also easier to construct from php data structures.

== Ajax in Moodle ==
{{ Moodle 2.9 }}

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions.

Some benefits of this system are:
# No new ajax scripts need auditing for security vulnerabilities
# Multiple requests can be chained in a single http request
# Strict type checking for all parameters and return types
# New webservice functions benefit Ajax interfaces and web service clients

So the steps required to create an ajax interaction are:

# Write or find an existing web service function to handle the ajax interaction: See [[ Web_services ]]
# White list the web service for ajax. To do this, you can define 'ajax' => true in your function's definition, in db/services.php. Only functions that are whitelisted using this mechanism will be available to the ajax script.
# Call the web service from javascript in response to a user action:

Example calling core_get_string:
<code javascript>
require(['core/ajax'], function(ajax) {
var promises = ajax.call([
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'pluginname' } },
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'changerate' } }
]);

promises[0].done(function(response) {
console.log('mod_wiki/pluginname is' + response);
}).fail(function(ex) {
// do something with the exception
});

promises[1].done(function(response) {
console.log('mod_wiki/changerate is' + response);
}).fail(function(ex) {
// do something with the exception
});
});
</code>

Note: This example chains to separate calls to the core_get_string webservice in one http request

Note: Don't actually fetch strings like this, it is just an example, use the 'core/str' module instead.

To update parts of the UI in response to Ajax changes, consider using [[ Templates ]]

For information on writing AJAX scripts for Moodle before Moodle 2.9 see: [[ AJAX pre 2.9 ]]

Watch a video about using templates with webservices and AJAX in Moodle: https://www.youtube.com/watch?v=UTePjRZqAg8

Tricky things to know about using webservices with ajax calls:
# Any call to $PAGE->get_renderer() requires the correct theme be set. If this is done in a webservice - it is likely that the theme needs to be a parameter to the webservice.
# Text returned from a webservice must be properly filtered. This means it must go through external_format_text or external_format_string (since 3.0 - see MDL-51213) with the correct context.
# The correct context for 2 is the most specific context relating to the thing being output e.g. for a user's profile desciption the context is the user context.
# After adding any dynamic content to a page, Moodle's filters need to be notified via M.core.event.FILTER_CONTENT_UPDATED (MDL-51222 makes this easier)

In some very rare cases - you can mark webservices as safe to call without a session. These should only be used for webservices that return 100% public information and do not consume many resources. A current example is core_get_string. To mark a webservice as safe to call without a session you need to do 2 things.
# Add 'loginrequired' => false to the service definition in db/services.php
# Pass "false" as the 3rd argument to the ajax "call" method when calling the webservice.
The benefit to marking these safe webservice is that (a) they can be called from the login page before we have a session and (b) they will perform faster because they will bypass moodles session code when responding to the webservice call.

== See also ==

* [[ AJAX pre 2.9 ]]
* [[Templates]]
* [[Javascript Modules]]
* [[Javascript FAQ]]
* [[Javascript]]
* [[Firebug#Debugging_AJAX_with_Firebug|Debugging AJAX with Firebug]]

* [http://www.adaptivepath.com/publications/essays/archives/000385.php ''Ajax: A New Approach to Web Applications'', the original Ajax article by Adaptive Path] (This link is now dead, but the article is on the [https://web.archive.org/web/20070225140912/http://www.adaptivepath.com/publications/essays/archives/000385.php Internet Archive])
* [http://developer.mozilla.org/en/docs/AJAX:Getting_Started ''AJAX: Getting Started'' article on developer.mozilla.org]
* [http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html ''10 places you must use AJAX'' by Adam Bosworth] (This link is now dead but the article is on the [https://web.archive.org/web/20060127015713/http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html Internet Archive]
* [http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype ''Considering Ajax, Part 1: Cut through the hype'' from IBM developerworks]
* [http://en.wikipedia.org/wiki/Ajax_%28programming%29 Wikipedia article on ''AJAX'']
* [http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ How to Make Your AJAX Applications Accessible: 40 Tutorials and Articles]
*[http://www.ajaxload.info/ AJAX loading icon generator]

[[Category:Javascript]]
[[Category:AJAX]]

AJAX

2016-10-04T06:29:27Z

Libertymoodle: /* Add Internet Archive link to 404 article */

'''AJAX (Asynchronous Javascript and XML)''' is a modern web design technique that allows for more interactivity by making webpages that fetch data in the background and alter themselves without reloading the entire page. This helps to make a page feel much more like an application than a web page. AJAX is a new way of working with existing technologies (including HTML, [[Javascript]], [[CSS]] and the ''XMLHttpRequest object'' amongst others) rather than a new piece of technology in itself.

Although AJAX indicates that XML is used, the term really relates to the group of technologies and in Moodle we tend to favour use of JSON rather than XML as the syntax is lighter and leads to a smaller output. It is also easier to construct from php data structures.

== Ajax in Moodle ==
{{ Moodle 2.9 }}

The preferred way to write new ajax interactions in Moodle is to use the javascript module "core/ajax" which can directly call existing web service functions.

Some benefits of this system are:
# No new ajax scripts need auditing for security vulnerabilities
# Multiple requests can be chained in a single http request
# Strict type checking for all parameters and return types
# New webservice functions benefit Ajax interfaces and web service clients

So the steps required to create an ajax interaction are:

# Write or find an existing web service function to handle the ajax interaction: See [[ Web_services ]]
# White list the web service for ajax. To do this, you can define 'ajax' => true in your function's definition, in db/services.php. Only functions that are whitelisted using this mechanism will be available to the ajax script.
# Call the web service from javascript in response to a user action:

Example calling core_get_string:
<code javascript>
require(['core/ajax'], function(ajax) {
var promises = ajax.call([
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'pluginname' } },
{ methodname: 'core_get_string', args: { component: 'mod_wiki', stringid: 'changerate' } }
]);

promises[0].done(function(response) {
console.log('mod_wiki/pluginname is' + response);
}).fail(function(ex) {
// do something with the exception
});

promises[1].done(function(response) {
console.log('mod_wiki/changerate is' + response);
}).fail(function(ex) {
// do something with the exception
});
});
</code>

Note: This example chains to separate calls to the core_get_string webservice in one http request

Note: Don't actually fetch strings like this, it is just an example, use the 'core/str' module instead.

To update parts of the UI in response to Ajax changes, consider using [[ Templates ]]

For information on writing AJAX scripts for Moodle before Moodle 2.9 see: [[ AJAX pre 2.9 ]]

Watch a video about using templates with webservices and AJAX in Moodle: https://www.youtube.com/watch?v=UTePjRZqAg8

Tricky things to know about using webservices with ajax calls:
# Any call to $PAGE->get_renderer() requires the correct theme be set. If this is done in a webservice - it is likely that the theme needs to be a parameter to the webservice.
# Text returned from a webservice must be properly filtered. This means it must go through external_format_text or external_format_string (since 3.0 - see MDL-51213) with the correct context.
# The correct context for 2 is the most specific context relating to the thing being output e.g. for a user's profile desciption the context is the user context.
# After adding any dynamic content to a page, Moodle's filters need to be notified via M.core.event.FILTER_CONTENT_UPDATED (MDL-51222 makes this easier)

In some very rare cases - you can mark webservices as safe to call without a session. These should only be used for webservices that return 100% public information and do not consume many resources. A current example is core_get_string. To mark a webservice as safe to call without a session you need to do 2 things.
# Add 'loginrequired' => false to the service definition in db/services.php
# Pass "false" as the 3rd argument to the ajax "call" method when calling the webservice.
The benefit to marking these safe webservice is that (a) they can be called from the login page before we have a session and (b) they will perform faster because they will bypass moodles session code when responding to the webservice call.

== See also ==

* [[ AJAX pre 2.9 ]]
* [[Templates]]
* [[Javascript Modules]]
* [[Javascript FAQ]]
* [[Javascript]]
* [[Firebug#Debugging_AJAX_with_Firebug|Debugging AJAX with Firebug]]

* [http://www.adaptivepath.com/publications/essays/archives/000385.php ''Ajax: A New Approach to Web Applications'', the original Ajax article by Adaptive Path] (This link is now dead, but the article is on the [https://web.archive.org/web/20070225140912/http://www.adaptivepath.com/publications/essays/archives/000385.php Internet Archive])
* [http://developer.mozilla.org/en/docs/AJAX:Getting_Started ''AJAX: Getting Started'' article on developer.mozilla.org]
* [http://www.sourcelabs.com/blogs/ajb/2005/12/10_places_you_must_use_ajax.html ''10 places you must use AJAX'' by Adam Bosworth]
* [http://www-128.ibm.com/developerworks/web/library/wa-ajaxtop1/?ca=dgr-lnxw01AjaxHype ''Considering Ajax, Part 1: Cut through the hype'' from IBM developerworks]
* [http://en.wikipedia.org/wiki/Ajax_%28programming%29 Wikipedia article on ''AJAX'']
* [http://www.maxkiesler.com/index.php/weblog/comments/how_to_make_your_ajax_applications_accessible/ How to Make Your AJAX Applications Accessible: 40 Tutorials and Articles]
*[http://www.ajaxload.info/ AJAX loading icon generator]

[[Category:Javascript]]
[[Category:AJAX]]

Talk:Web service API functions

2016-05-18T06:21:56Z

Libertymoodle: /* CORS */

==Feedback here please==

What is the point of the moodle_ prefix? I think it is just a waste of space and should be deleted.--[[User:Tim Hunt|Tim Hunt]] 18:38, 18 August 2011 (WST)

The table in the '''Web service protocols''' section has a column called "CORS". What is "CORS"? Is it http://www.w3.org/TR/cors/? --[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 14:21, 18 May 2016 (AWST)

GSOC/2016

2016-04-26T15:23:35Z

Libertymoodle: /* See also */

An overview of the Google Summer of Code 2016 projects for Moodle.

==tool_pluginkenobi: guide to plugin creation==

* Student: [https://moodle.org/user/view.php?id=2024009&course=5 Alexandru Elisei]
* Mentor: David Mudrak

==Adding search to more Moodle components==

* Student: [https://moodle.org/user/view.php?id=2039167&course=5 Devang Gaur]
* Mentor: David Monllaó

==Atto image resize/crop/rotate==

* Student: [https://moodle.org/user/view.php?id=1953983&course=5 Joey Andres]
* Mentor: Mark Nelson

==Add support to end-to-end testing in the Mobile app==

* Student: [https://moodle.org/user/view.php?id=2065840&course=5 Supun Wanniarachchi]
* Mentor: Juan Leyva

==See Also==
[http://www.moodleworld.com/moodle-announces-gsoc-participants-gsoc-summerofcode-moodle/ Moodle announces GSoC participants]

Talk:GSOC/2016

2016-04-26T15:20:59Z

Libertymoodle: /* Deleted comment. Should have googled before adding this comment */

GSOC/2016

2016-04-26T15:18:05Z

Libertymoodle: /* See also */

An overview of the Google Summer of Code 2016 projects for Moodle.

==tool_pluginkenobi: guide to plugin creation==

* Student: [https://moodle.org/user/view.php?id=2024009&course=5 Alexandru Elisei]
* Mentor: David Mudrak

==Adding search to more Moodle components==

* Student: [https://moodle.org/user/view.php?id=2039167&course=5 Devang Gaur]
* Mentor: David Monllaó

==Atto image resize/crop/rotate==

* Student: [https://moodle.org/user/view.php?id=1953983&course=5 Joey Andres]
* Mentor: Mark Nelson

==Add support to end-to-end testing in the Mobile app==

* Student: [https://moodle.org/user/view.php?id=2065840&course=5 Supun Wanniarachchi]
* Mentor: Juan Leyva

===See Also===
[http://www.moodleworld.com/moodle-announces-gsoc-participants-gsoc-summerofcode-moodle/ Moodle announces GSoC participants]

Talk:GSOC/2016

2016-04-26T15:09:06Z

Libertymoodle: /* More info */

== tool_pluginkenobi ==
The tool_pluginkenobi project looks interesting! Can you provide more details.
--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 23:08, 26 April 2016 (AWST)

Talk:lib/formslib.php Usage

2016-04-01T14:02:28Z

Libertymoodle: /* Doc needs clarity */

The sample code on this page refers to '''$fromform''':

<code php>
} else if ($fromform = $mform->get_data()) {
</code>

What is '''$fromform''' and where is it defined?

Talk:Form API

2016-04-01T13:54:47Z

Libertymoodle: /* Doc needs clarity */

== Usage ==
This section says: "For creating a form in moodle, you have to create class extending moodleform class", but WHERE do you create this class? Which .php file? Is it simplehtml_form.php?

Below the "class simplehtml_form extends moodleform" sample code the doc then says: "Then instantiate form (in this case simplehtml_form) on your page." Where do you instantiate the form? In the view.php page?

Lastly, where do you put the code that processes and saves the form data when the form is submitted?

The documentation should be clear about where you should put all the different sections of code.

Talk:Form API

2016-04-01T13:44:23Z

Libertymoodle: /* Doc needs clarity */

== Usage ==
This section says: "For creating a form in moodle, you have to create class extending moodleform class", but WHERE do you create this class? Which .php file? The documentation should be clear about where you should put all the different sections of code.
Where do you put the "class simplehtml_form extends moodleform..." code? Where do you put the code that processes the form data when the form is submitted?

Talk:Form API

2016-04-01T13:41:41Z

Libertymoodle: /* Doc needs clarity */

== Usage ==
This section says: "For creating a form in moodle, you have to create class extending moodleform class", but WHERE do you create this class? Which .php file?

lib/formslib.php Usage

2016-03-03T13:05:31Z

Libertymoodle: Undo revision 49552 by Nadavkav (talk) - It's better to link to the Internet Archive copy of the midnighthax.com page instead of deleting the link.

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

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

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

Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://web.archive.org/web/20130630141100/http://www.midnighthax.com/quickform.php slightly longer one] particularly useful (Note: the original docs on the midnighthax.com domain no longer exist, so this link now points to the Internet Archive copy of the site).

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

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

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

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

// Setup $PAGE here.

$mform = new yourmod_formfunction_form();//name of the form you defined in file above.
// Default 'action' for form is strip_querystring(qualified_me()).

// Set the initial values, for example the existing data loaded from the database.
// (an array of name/value pairs that match the names of data elements in the form.
// You can also use an object)
$mform->set_data($toform);

if ($mform->is_cancelled()) {
// You need this section if you have a cancel button on your form
// here you tell php what to do if your user presses cancel
// probably a redirect is called for!
// PLEASE NOTE: is_cancelled() should be called before get_data().
redirect($returnurl);

} else if ($fromform = $mform->get_data()) {
// This branch is where you process validated data.
// Do stuff ...

// Typically you finish up by redirecting to somewhere where the user
// can see what they did.
redirect($nexturl);
}

echo $OUTPUT->header();
$mform->display();
echo $OUTPUT->footer();
</code>

You are encouraged to look at '''lib/formslib.php''' to see what additional functions and parameters are available. Available functions are well commented.

===Defining Your Form Class===

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

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

====definition()====

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

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

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

====defaults_preprocessing====

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

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

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

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

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

[[Category:Formslib]]

Theme checklist

2016-02-01T05:58:59Z

Libertymoodle: /* Typos */

{{Template:Themes}}So, you think your theme is finished? Well, Moodle is a big complex system and there are lots of obscure corners that you might not know about. This page lists lots of things that you might have missed when working on your theme. To be sure your theme is really complete, you need to check these out.

== Accessible colours ==

Are the colours you have chosen accessible? Is there a reasonable contrast difference between them?

== All the different forms of the front page ==

Depending on how many courses there are in your Moodle site, and how many of them the current user is enrolled in, the [[:en:Front_page|front page]] looks different. Have you tested all the different ways it can look?

== Big report tables ==

The [[:en:Gradebook|grader report]], and other similar reports like the quiz reports, are very big tables that don't fit on one screen. How does your theme cope. Is it easy for the teacher to scroll sideways to see all the data?

== Clean install ==

Have you installed and un-installed the theme on a 'pure' installation? That is an installation with no other contributed plugins. This allows you to check for unintentional dependencies.

== Code checker ==

[https://moodle.org/plugins/view.php?plugin=local_codechecker Code checker] checks your code against the Moodle [https://docs.moodle.org/dev/Coding coding standards]. It is a useful tool for spotting issues and making your code readable to all who are familiar with the core code. Do not take all messages literally, use your common sense and make changes that are sensible.

== Dependencies ==

Have you specified the correct dependencies for both parent themes and Moodle in the '[https://docs.moodle.org/dev/version.php version.php]' file?

== Fake blocks ==

While you are looking at the quiz, pay attention to the [[:en:Using_Quiz|Quiz navigation block]]. This is not a normal block that teachers or admins can add or remove, it is a 'Fake block' that looks like any other block but is part of the Moodle UI. Are you happy with where it appears, and how it looks?

Other parts of Moodle that use fake blocks are the [[:en:Lesson_module|Lesson activity]] and [[:en:Calendar|the calendar UI]].

Fake blocks are attached to the first region or the 'defaultregion' in the 'regions' array for the 'layout' in the 'layouts' array in the 'config.php' file. So if the order is ('side-pre', 'side-post') and you want fake blocks to be in 'side-post' change the 'defaultregion' to 'side-post' and the 'regions' array to ('side-post', 'side-pre').

===Adding a fake block to each pagelayout in your theme:===
(add following function to theme/yourtheme/lib.php)
<code php>
function theme_yourtheme_get_html_for_settings(renderer_base $output, moodle_page $page) function:

$bc = new block_contents();
$bc->title = 'fake title';
$bc->attributes['class'] = 'fakeblock';
$bc->content = 'fake content';
$page->blocks->add_fake_block($bc, 'side-pre');

</code>

== Instructions ==

Have you provided a 'readme' file containing: Install instructions, un-install instructions, version history and contact details for when things go wrong.

== License ==

Is all code GPLv3 (or compatible) licensed?

== Maturity ==

Have you correctly stated the maturity of the theme in the '[https://docs.moodle.org/dev/version.php version.php]' file? This gives users and idea of how stable the code is.

== Quiz 'secure' pop-up ==

When a quiz set to [[:en:Quiz_settings#Extra_restrictions_on_attempts|Full screen pop-up with some JavaScript security]] then the page uses a special 'secure' layout template that should have minimal headers or links.

== Readable fonts ==

Are the fonts you have chosen readable? Will they be difficult to read on small devices?

== Right-to-left languages ==

In languages like Hebrew or Farsi, lots of things that you made left-aligned probably need to be right-aligned instead. Moodle adds .dir-rtl or .dir-ltr class to the body element, which you can use in CSS rules.

== Responsive ==

Have you tested your theme for responsiveness on small devices? Try resizing the browser window and see how it reacts.

== Theme developer mode ==

When 'Theme developer mode' is 'on', all of the CSS files are sent individually. When it is 'off', they are all combined together. This can lead to some issues. Check that your theme works with 'Theme designer mode off'.

== ... please add more things here in alphabetical order ... ==

Talk:Webservice protocols

2015-12-07T19:34:38Z

Libertymoodle: Provide examples of WS calls

==webservice/myprotocol/server.php==
This topic says: "The web service clients will call this file with the web service function name/parameters and the web service token." Can you provide some examples of this call so we can see what it looks like?

User:Luis de Vasconcelos

2015-10-31T21:44:42Z

Libertymoodle:

Moodle sysadmin and developer at Liberty Life, South Africa

User:Petr Škoda (škoďák)

2015-10-31T21:36:39Z

Libertymoodle:

* independent developer working for Totara Learning Solutions

Talk:Testing of integrated issues

2014-11-20T09:27:57Z

Libertymoodle: iTeam

== iTeam ==
Who or what is the "iTeam"?
This article shouldn't assume that the reader is familiar with HQ terms.

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 17:27, 20 November 2014 (AWST)

== Providing instructions for testers should be compulsory for HQ developers ==

Suggestion: Either MDL or PULL ticket must provide exact instructions for testers how the patch can be tested from user's perspective. Testers are not expected to study the source code change to construct the test case on their own. If the PULL request comes from an HQ employee and steps to test are not provided, the test would fail automatically. --[[User:David Mudrak|David Mudrak]] 14:03, 17 January 2011 (UTC)

==Schedule==

Suggested timing:

* Integration reviewing - Monday up to Tuesday 12 noon UTC
* Testing - Tuesday up to Wednesday 12 noon UTC

Once the last pull request for the week is reviewed, the QA Testing Site can be updated from the integration server. --[[User:Helen Foster|Helen Foster]] 14:52, 19 January 2011 (UTC)

==Broken Link==
The "testing process" section on https://docs.moodle.org/dev/Testing_of_integrated_issues links to https://tracker.moodle.org/browse/PULL but that https://tracker.moodle.org/browse/PULL address returns a "Project Does Not Exist" error. What is the current URL?

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 20:43, 1 July 2013 (WST)

Migrating logging calls in plugins

2014-11-03T13:12:52Z

Libertymoodle: /* See also */

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about event name; specifically, there is a restricted [[Event 2#Verb list|list of available verbs]].

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<code php>
$string['eventEVENTNAME] = 'Something has happened';
</code>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The EVENTNAME event.
*
* @package FULLPLUGINNAME
* @copyright 2014 YOUR NAME
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
/**
* The EVENTNAME event class.
*
* @property-read array $other {
* Extra information about event.
*
* - PUT INFO HERE
* }
*
* @since Moodle MOODLEVERSION
* @copyright 2014 YOUR NAME
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
**/
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "The user with id {$this->userid} created ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_logdata() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</code>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<code php>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</code>

...becomes...

<code php>
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</code>

If you need to trigger event multiple times in the code, or just prefer shorter syntax, you can declare your own static create function in the event class that would populate necessary fields and even add snapshots (see examples in mod_assign). In this case you can triger event in one line:

<code php>
\FULLPLUGINNAME\event\EVENTNAME::create_from_someobject($someobject)->trigger();
</code>

=== Step 4. Increase the version number in version.php===

The events that exist are only scanned when a plugin is installed or updated. Therefore when you change events, you need to increase the plugin's version number in its version.php to prompt an upgrade.

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<code php>
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</code>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<code php>
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
// In the next line you can use $PAGE->activityrecord if you have set it, or skip this line if you don't have a record.
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord);
$event->trigger();
</code>

===Step 4. Update version.php===
Don't forget to update the plugin version number to prompt an upgrade.

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<code php>
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</code>

=== Step 3. Triggering the event ===

<code php>
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</code>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Objecttable is the table that best represents the event object. Usually it is the object where the "CRUD" action was performed. This table is used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/MOODLE_27_STABLE/lib/classes/event/course_module_deleted.php#L71
* Triggering:https://github.com/moodle/moodle/blob/MOODLE_27_STABLE/course/lib.php#L1737..L1747
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added, it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect a record snapshot identified by 'objecttable' and 'objectid' but developers may also add snapshots of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be fetched at any time between the triggering of event and its observation.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

Always use developer debugging mode when doing development. A lot of useful build-in validation will only work in development mode.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

In order to manually test the event you can perform the action and check how it appears in '''Course Administration > Reports > Logs'''. Also look up your event in the '''Site Administration > Reports > Events list'''.

== "Installation" of events ==

Remember that you have to bump the plugin version in order to prompt an upgrade so that new events will be "installed".

==See also==
The [https://github.com/markn86/moodle-mod_certificate/pull/34 '''add_to_log deprecated, replace with events'''] issue on Github illustrates how the deprecated '''add_to_log()''' calls in the Certificate Module were upgraded to the new events method.

Migrating logging calls in plugins

2014-11-03T13:10:52Z

Libertymoodle: Add 'See Also' link

This document is aimed to assist developers in replacing existing '''add_to_log()''' and '''events_trigger()''' calls with events. This can be implemented in Moodle 2.6 and will be required in 2.7.

As a quick reminder: [[Event 2|new events]] were introduced in Moodle 2.6, a new [[Logging 2|logging system]] is being introduced in Moodle 2.7. The '''add_to_log()''' function will be deprecated, but the existing log table will still be present with existing data intact. This original logging is now called ''legacy logging''. The new and legacy logging may coexist in the legacy logging system for purposes of transition, but this is not recommended for performance reasons. When replacing calls to add_to_log() with the triggering of an event, developers must ensure that they also generate an entry for the legacy log. It will only be used if the legacy log is enabled, since it may be enabled on systems that continue to use custom reports relying on presence of the legacy log table and it may take time to migrate such reports.

== Quick guide ==

If you are replacing common add_to_log() calls such as "view" and "view all" in mod/XXX/view.php and mod/XXX/index.php, see below. Otherwise do the following.

=== Step 1. Choose a name for the event ===

Names should follow the syntax OBJECT_VERB, for example "entry_added", "work_submitted", etc. It does not need to include a plugin name because this can be obtained from the PHP class namespace. See [[Event 2|the events documentation]] for more details about event name; specifically, there is a restricted [[Event 2#Verb list|list of available verbs]].

Define a language string for the event name in '''YOURPLUGINDIR/lang/en/FULLPLUGINNAME.php'''.
<code php>
$string['eventEVENTNAME] = 'Something has happened';
</code>

=== Step 2. Create event class ===

For each event you must create an event class in '''YOURPLUGINDIR/classes/event/EVENTNAME.php''', with the following format.
<code php>
<?php
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The EVENTNAME event.
*
* @package FULLPLUGINNAME
* @copyright 2014 YOUR NAME
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
/**
* The EVENTNAME event class.
*
* @property-read array $other {
* Extra information about event.
*
* - PUT INFO HERE
* }
*
* @since Moodle MOODLEVERSION
* @copyright 2014 YOUR NAME
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
**/
class EVENTNAME extends \core\event\base {
protected function init() {
$this->data['crud'] = 'c'; // c(reate), r(ead), u(pdate), d(elete)
$this->data['edulevel'] = self::LEVEL_PARTICIPATING;
$this->data['objecttable'] = '...';
}

public static function get_name() {
return get_string('eventEVENTNAME', 'FULLPLUGINNAME');
}

public function get_description() {
return "The user with id {$this->userid} created ... ... ... with id {$this->objectid}.";
}

public function get_url() {
return new \moodle_url('....', array('parameter' => 'value', ...));
}

public function get_legacy_logdata() {
// Override if you are migrating an add_to_log() call.
return array($this->courseid, 'PLUGINNAME', 'LOGACTION',
'...........',
$this->objectid, $this->contextinstanceid);
}

public static function get_legacy_eventname() {
// Override ONLY if you are migrating events_trigger() call.
return 'MYPLUGIN_OLD_EVENT_NAME';
}

protected function get_legacy_eventdata() {
// Override if you migrating events_trigger() call.
$data = new \stdClass();
$data->id = $this->objectid;
$data->userid = $this->relateduserid;
return $data;
}
}
</code>

=== Step 3. Trigger the event instead of add_to_log() ===

Replace the add_to_log() with an event trigger. The following is a common example of an event trigger inside an activity module.
<code php>
add_to_log($course->id, 'PLUGINNAME', 'LOGACTION', '...........', $objid, $cmid);
</code>

...becomes...

<code php>
$event = \FULLPLUGINNAME\event\EVENTNAME::create(array(
'objectid' => $objid,
'context' => context_module::instance($cmid)
));
$event->trigger();
</code>

If you need to trigger event multiple times in the code, or just prefer shorter syntax, you can declare your own static create function in the event class that would populate necessary fields and even add snapshots (see examples in mod_assign). In this case you can triger event in one line:

<code php>
\FULLPLUGINNAME\event\EVENTNAME::create_from_someobject($someobject)->trigger();
</code>

=== Step 4. Increase the version number in version.php===

The events that exist are only scanned when a plugin is installed or updated. Therefore when you change events, you need to increase the plugin's version number in its version.php to prompt an upgrade.

== Replacing 'view' events in modules ==

Calls to add_to_log() to report a 'view' event are usually found in mod/PLUGINNAME/view.php (or in a lib function included by this file) and indicate that a user viewed the module.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_viewed.php''' with the following format.
<code php>
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_viewed extends \core\event\course_module_viewed {
protected function init() {
$this->data['objecttable'] = 'PLUGINNAME';
parent::init();
}
// You might need to override get_url() and get_legacy_log_data() if view mode needs to be stored as well.
}
</code>

=== Step 3. Triggering the event ===

This example takes data from $PAGE object but you may substitute this with ids and objects that you have fetched.
<code php>
$event = \FULLPLUGINNAME\event\course_module_viewed::create(array(
'objectid' => $PAGE->cm->instance,
'context' => $PAGE->context,
));
$event->add_record_snapshot('course', $PAGE->course);
// In the next line you can use $PAGE->activityrecord if you have set it, or skip this line if you don't have a record.
$event->add_record_snapshot($PAGE->cm->modname, $activityrecord);
$event->trigger();
</code>

===Step 4. Update version.php===
Don't forget to update the plugin version number to prompt an upgrade.

== Replacing 'view all' events in modules ==

Calls to add_to_log using 'view_all' are usually found in mod/PLUGINNAME/index.php (or in a lib function included by this file). These invents indicate that a user viewed the list of all instances of this module within the course.

=== Step 1. Choosing the name ===

Because this is a common event, the name is already chosen: '''course_module_instance_list_viewed''' and the language string is defined in core.

=== Step 2. Defining class ===

You must create a class for this event in '''YOURPLUGINDIR/classes/event/course_module_instance_list_viewed.php''' with the following structure.
<code php>
namespace FULLPLUGINNAME\event;
defined('MOODLE_INTERNAL') || die();
class course_module_instance_list_viewed extends \core\event\course_module_instance_list_viewed {
}
</code>

=== Step 3. Triggering the event ===

<code php>
$event = \FULLPLUGINNAME\event\course_module_instance_list_viewed::create(array(
'context' => context_course::instance($course->id)
));
$event->trigger();
</code>

== What to include in the event ==

=== init() and create() ===

Ideally all information needed when initialising and triggering events should already be available without having to run additional queries. Queries run to fill event objects with data will cause additional performance load, which should be avoided. Information that needs to be gathered from the database should be provided by other event methods, which can be called selectively when needed.

As you noticed in the examples above you can specify additional properties either by the overriding the init() method of the event or when calling create(). The first way is used for properties that are always the same for this event, the second is for dynamic properties that may differ when the event is triggered.

Usually you need to include the following properties.
{| class="nicetable"
|-
| '''context''' or '''contextid'''
| required
| Describes the context where the event took place.
| If you want to hardcode the system context, do so in init().
|-
| '''crud'''
| required
| Describes whether the event reflects creation (c), reading (r), updating (u) or deleting (d). This should be a single character string.
| Most often are specified in init().
|-
| '''edulevel'''
| required
| The level of educational value of the event. Can be LEVEL_TEACHING, LEVEL_PARTICIPATING or LEVEL_OTHER.
| Most often are specified in init().
|-
| '''objecttable''' and '''objectid'''
|
| Objecttable is the table that best represents the event object. Usually it is the object where the "CRUD" action was performed. This table is used by events that show the change in one record of one table, which will be the case for the most events.
| Since 'objecttable' is always the same it is usually specified in init().
|-
| '''relateduserid'''
|
| The id of the user affected by the event.
| Only used if it is easy to identify a single user who is affected by this operation. For example a user who is being graded, a user who receives the message, a user being enrolled, etc. '''This is NOT the user who performs the action''' (who is identified in the userid field).
|-
| '''other'''
|
| Everything else that you may think is important about this event. This property will be serialised and stored by loggers.
| Include only necessary information. It can be used in get_description(), get_url() and get_legacy_logdata(). This property should only contain an array or scalar value, it '''can not use objects'''.
Example of information stored in 'other' can be found in event course_module_deleted:
* Definition: https://github.com/moodle/moodle/blob/MOODLE_27_STABLE/lib/classes/event/course_module_deleted.php#L71
* Triggering:https://github.com/moodle/moodle/blob/MOODLE_27_STABLE/course/lib.php#L1737..L1747
|}

Usually you don't need to include the following properties as they are deduced by the base class.
* 'userid': user who performs the action, taken from $USER
* 'courseid': course affected in the operation, which will be taken from context. It need not be specified at all for events that are not related to a particular course.

See the [[Event_2#Information_contained_in_events|full list of properties]] for more information.

=== get_legacy_logdata() ===

This method is used to add log data to the legacy log. You need only override this method when replacing an add_to_log() call. Since this document is a transition guide from add_to_log() to events, you will most likely need to override this method. This method needs to return an array (with 3-7 elements) that imitates the arguments that used to be passed to the add_to_log() function. From Moodle 2.7, the get_legacy_logdata() method will only be called if legacy logging is enabled through the legacy logging plugin.

=== get_description() and get_url() ===

Most reporting tools will display aggregated event information (for example the count of student logins) so those methods, which describe individual events, are not likely to be called often; they will only be used by detailed reports such as loglive. At the moment, use get_description() to provide a very brief internal description of the action performed, so that it can be used for error recovery like any other system log. The description is hard-coded in English but it may be possible that future versions of Moodle (2.8 or later) will allow the use of translatable language strings. These methods should not make DB queries, access global variables, etc. For example, when a course is renamed or when a user is deleted, do not retrieve the course name or user name, instead simply use their ids. These functions should return exactly the same result whenever they are called, regardless of the environment or state, even after they have been restored from logs.

=== get_legacy_eventname() and get_legacy_eventdata() ===

You will need to override these two functions if you are upgrading events_trigger() calls. These will allow legacy plugins to continue to listen to your new events without upgrading their listeners.

If you need to provide more detailed information to observers, you can choose to:
* add more information to 'other', but remember that this will be logged and it's better to keep logs as small as possible;
* use record snapshots, which are especially useful for delete actions (you can call get_record_snapshot() inside get_legacy_eventdata() and observers are encouraged to get data from snapshots as well);
* add new properties to your event class and define getter/setter functions, for example set_custom_data() and get_custom_data().

=== add_record_snapshot() ===

A record snapshot can be added for any DB table related to the event. If it is added, it must be an instance of stdClass containing all fields that are present in the corresponding DB table. You must add a record snapshot when you delete something from database. '''Record snapshots cannot be used from reports, it is intended for event observers only.''' Usually observers expect a record snapshot identified by 'objecttable' and 'objectid' but developers may also add snapshots of related tables, i.e. when book chapter is updated the developer may decide to add snapshots of related records in tables book_chapters, book, course_modules and course.

Record snapshots should be added only when you already have an object and do not need to perform any additional DB queries to retrieve it. Otherwise omit it, as the record will be retrieved by get_record_snapshot() automatically, and only if needed. For performance reasons the snapshots are not guaranteed to contain an exact state at the time of event triggering, it may be fetched at any time between the triggering of event and its observation.

== Events DON'Ts ==

Do not put more information in 'other' than is needed. For example, do not include a full DB record for delete/create operations or a list of all changed properties in edit operations. If observers are interested in this information, it can requested by calling get_record_snapshot(). Never include large text fields in event data. '''Please help to keep the log size reasonable.'''

Do NOT use $USER, $COURSE, $PAGE or other global variables when overriding get_* methods (with the exception of get_legacy_eventdata).

Do NOT call $this->get_record_snapshot() inside the event class (again with the exception of get_legacy_eventdata). If you need additional information for internal functions that cannot be added to existing properties, add it to the 'other' property.

Do NOT use $this->context inside an event class. '''Remember that methods get_description() and get_url() may be called on events after they have been restored from logs.''' It is possible that the original context no longer exists when these functions are called. Instead use $this->contextid, $this->contextlevel, $this->contextinstanceid.

== Validation and testing ==

You may notice that the most of events in Moodle also have function validate_data() . You can add this function for your own safety to ensure that you don't forget to define all required data when triggering event.

Always use developer debugging mode when doing development. A lot of useful build-in validation will only work in development mode.

We highly recommend to cover your events with unit tests. Search in standard plugins for files with the names events_test.php to see examples.

In order to manually test the event you can perform the action and check how it appears in '''Course Administration > Reports > Logs'''. Also look up your event in the '''Site Administration > Reports > Events list'''.

== "Installation" of events ==

Remember that you have to bump the plugin version in order to prompt an upgrade so that new events will be "installed".

==See also==
The [https://github.com/markn86/moodle-mod_certificate/pull/34 '''add_to_log deprecated, replace with events'''] issue on Github illustrates how the '''deprecated add_to_log()''' calls in the Certificate Module were upgraded to the new events method.

Talk:Reports

2014-04-03T15:38:19Z

Libertymoodle: /** Page and folder POSITION **/

==How your report gets included in the navigation==
This section says that "by default, your report will be included in the admin tree under the 'Reports' section". How does Moodle determine the POSITION of your report in that 'Reports' section?

And how can you force your report to appear in a specific position in that 'Reports' folder, e.g. the top?

You can use this code to create a FOLDER in which you can put your report(s):

<code php>
$ADMIN->add('reports', new admin_category('my_reports', get_string('my_reports','report_my_reports')));
</code>

but how do you force that folder to always appear at the top (or bottom) of the 'Reports' folder?

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 23:38, 3 April 2014 (WST)

Talk:Admin reports

2014-04-03T14:47:55Z

Libertymoodle: /** Admin tree POSITION **/

==How your report gets included in the admin tree==
This section says that "by default, your report will be included in the admin tree under the 'Reports' section". How does Moodle determine the POSITION of your report in that 'Reports' section?

And how can you force your report to appear in a specific position in that 'Reports' folder, e.g. the top?

You can use this code to create a FOLDER in which you can put your report(s):

<code php>
$ADMIN->add('reports', new admin_category('my_reports', get_string('my_reports','report_my_reports')));
</code>

but how do you force that folder to always appear at the top (or bottom) of the 'Reports' folder?

--[[User:Luis de Vasconcelos|Luis de Vasconcelos]] ([[User talk:Luis de Vasconcelos|talk]]) 22:47, 3 April 2014 (WST)

Talk:lib/formslib.php Form Definition

2014-02-07T12:39:04Z

Libertymoodle: /* Dependent Dropdown Lists */

There's items on here (e.g. 'duration') that are 2.0 only. Please can people adding them mark them as such to avoid confusion. Ta --[[User:Howard Miller|Howard Miller]] 11:42, 23 July 2009 (UTC)

: Hi Howard, You can just add <nowiki>{{Moodle 2.0}}</nowiki> to those items. I did that for 'duration'. --[[User:Frank Ralf|Frank Ralf]] 11:54, 23 July 2009 (UTC)

==No default value attribute for editor??==
tried the context key but doesn't work.

== Use Static elements with care? ==

Why are static elements listed as being used with care?

== ''Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.'' ==

I'm really not sure what this means. Does it actually mean "do not create elements that are conditional upon the values of other submitted elements" as opposed to not creating conditional elements at all? Lots of forms have conditional elements --[[User:Howard Miller|Howard Miller]] 13:06, 6 February 2011 (UTC)

Yes, it means don't create things that are conditional on the data that the form will be editing. It is OK to condition on admin settings (e.g. if conditional activities are turned off, those options do not appear on the mod_edit forms. Or, perhaps, on capabilities. However, in that case you have to be careful. If someone without the capability uses the form, you have to make sure that when they submit, you don't overwrite the correct value in the database with blank from the form. In that situation, it may be better to use hardFreeze on those form elements, instead of conditionally omitting them.--[[User:Tim Hunt|Tim Hunt]] 15:14, 6 February 2011 (UTC)

== Very disappointing, that nested fieldsets are not supported :( ==

''"$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));''
''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."''<br>

'''Should be possible to nest fieldsets!'''
'''Please add this feature!'''

'''As I know this feature was already added to QuickForms.'''<br>
'''See example QuickForm solution of nested fieldset here:'''<br>
[http://pear.saltybeagle.com/HTML_QuickForm_Renderer_Tableless/stack.php http://pear.saltybeagle.com/HTML_QuickForm_Renderer_Tableless/stack.php]<br>
Konrad Lorinczi [[User:- -|- -]] 18:02, 23 March 2011 (UTC)

== Multiple file uploads? ==

If one has multiple files to be uploaded using the form and all files are to go in different location. It feels like, the below code does not satisfy the needs to do anything of this sort.
------------------------------------------
after form submission and validation use

if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
--------------------------------------------
How this can be done?
Thanks.

==Dependent Dropdown Lists==

Does Formslib support adding dependent dropdown lists to a form? This is where the options that are displayed on list2 are dependent on the option that is selected on list1.
The [https://moodle.org/mod/forum/discuss.php?d=163019 how to implement dependent dropdown lists] discussion on the Using Moodle forum talks about something similar and offers a "hacky" approach. But that was in 2010. Can this be easily done in Moodle 2.5/2.6?

Talk:YUI

2013-12-03T16:26:39Z

Libertymoodle: Applicable versions

==Applicable Version==
Does this page only apply to Moodle version 2.0, like the {Moodle 2.0} label implies? Or is this still relevant to the current versions of Moodle (2.5/2.6)?

Windows Installer

2013-08-14T13:10:47Z

Libertymoodle: /* Resources: fix 404 link */

== Windows Installer Package ==
The Windows Installer is based on xampp 1.6 distribution. The package structure is the following:

Root
| '''Readme.txt'''
| '''Start Moodle.exe'''
| '''Stop Moodle.exe'''
| server
| apache_start.bat
| apache_stop.bat
| makecert.bat
| mysql_start.bat
| mysql_stop.bat
| readme_de.txt
| readme_en.txt
| service.exe
| setup_xampp.bat
| xampp_restart.bat
| xampp_start.exe
| xampp_stop.exe
| xampp_control.exe
| xampp_portcheck.exe
| apache
| cgi-bin
| install
| licences
| '''moodle'''
| '''moodledata''' ''//this folder is created during the installation process''
| mysql
| php
| sendmail
| tmp

== Moodle folders ==
All moodle files must be located in server/moodle/

== 'Start/Stop Moodle.exe' ==
Windows Installer package comes with two executable files. 'Start Moodle.exe' sets up the Xampp environment and launch Apache and Mysql processes. 'Stop Moodle.exe' stop the two processes. This section explains how to create these two executable files.

=== 1. Create a batch file ===
The two batch files can be download on CVS: http://cvs.moodle.org/contrib/tools/m4w_builder/bin/batch/
==== 'Start Moodle.exe' ====
This batch file readjusts, if needed, apache/mysql paths to the new location in hard disk. (server/setup_xampp.bat)
Then it launchs Apache and Mysql processes. (server/xampp_start.exe)

==== 'Stop Moodle.exe' ====
This batch file stops the apache and mysql process. (server/xampp_start.exe)

=== 2. Create an icon ===
In order to create an icon for an executable file you can use SnIco Edit. You need to save your icon as a .ico file.

=== 3. Create an executable file ===
Once you've got a batch file and an icon file, run bat_to_exe_converter.exe. Browse for the .bat file and the .ico file, then click on Compile. An executable file is generated.
The two generated files (and a Readme.txt) need to be copied into the Windows Installer zip at the root level. This is done by a script shell generating the windows installer package.

== Resources ==
You can find all resources in CVS: http://cvs.moodle.org/contrib/tools/m4w_builder/bin/

* [http://www.apachefriends.org/en/xampp.html Xampp]: the WAMP distribution used in the Windows Installer package.
* [http://www.snidesoft.eu SnIco Edit]: create/edit your .ico icon file.
* [http://www.f2ko.de/programs.php?lang=en&pid=b2e Bat to Exe Converter]: convert a .bat file into a .exe file.
* [http://www.jrsoftware.org/isinfo.php Inno Setup]: create a Windows Installer software. (setup.exe)

Talk:Developer meeting July 2013

2013-07-30T09:55:05Z

Libertymoodle: /* Dev Chat */

==Dev Chat==
Who has access to the [https://moodle.org/local/chatlogs/info.php "Regular Dev chat"]? I get a "Sorry, but you do not currently have permissions to do that (View chat logs)" message when I go there.