https://docs.moodle.org/30/en/api.php?action=feedcontributions&user=Delius&feedformat=atomMoodleDocs - User contributions [en]2024-03-28T21:05:15ZUser contributionsMediaWiki 1.39.6https://docs.moodle.org/30/en/index.php?title=Questions&diff=106588Questions2013-09-12T07:04:50Z<p>Delius: /* Question types */ Fixed link</p>
<hr />
<div>{{Managing a Moodle course}}<br />
Questions can be created in Moodle for use in [[Quiz module|quizzes]] and for import into [[Lesson module|lessons]].<br />
<br />
==[[Question types]]==<br />
*[[Calculated question type|Calculated]]<br />
*[[Simple calculated question type|Simple Calculated]]<br />
*[[Calculated multichoice question type|Calculated Multichoice]]<br />
*[[Description question type|Description]]<br />
*[[Essay question type|Essay]]<br />
*[[Matching question type|Matching]]<br />
*[[Embedded Answers (Cloze) question type|Embedded Answers (Cloze)]]<br />
*[[Multiple Choice question type|Multiple Choice]]<br />
*[[Short-Answer question type|Short-Answer]]<br />
*[[Numerical question type|Numerical]]<br />
*[[True/False question type|True/False]]<br />
*[[Third-party_question_types|Third-party question types]]<br />
<br />
==See also==<br />
*[[Managing questions]]<br />
**[[Question bank]]<br />
**[[Question categories]]<br />
**[[Import questions]]<br />
**[[Export questions]]<br />
*[[Question behaviours]]<br />
*[[Questions FAQ]]<br />
<br />
[[de:Fragen]]<br />
[[fr:Questions]]<br />
[[Category:Questions]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=question/type/stack&diff=106562question/type/stack2013-09-09T04:27:03Z<p>Delius: Redirected page to STACK question type</p>
<hr />
<div>#REDIRECT [[STACK_question_type]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Workshop_activity&diff=76879Workshop activity2010-10-20T12:29:39Z<p>Delius: /* Setup phase */</p>
<hr />
<div>{{Moodle 2.0}}<br />
<br />
[[Image:workshop_icon_logo.gif]]<br />
'''Workshop''' is a complex peer assessment activity with many options. It was the very first contributed module, but it had been largely unmaintained for a long time except for emergency fixes by various developers to keep it operational. By default, it is hidden in Moodle 1.9 in the ''Site administration > Modules > Manage activities''. Users are discouraged from using it in Moodle 1.x versions due to a number of known problem in these versions.<br />
<br />
The Workshop module was completely redesigned and rewritten for Moodle 2.0, using fresh new technology, APIs and features offered by this release. This page documents Workshop for Moodle 2.0. For more information on using Workshop in Moodle 1.x, please refer to the resources listed in ''See also'' section.<br />
<br />
== Key features ==<br />
<br />
Workshop is similar to the [[Assignment module]] and extends its functionality in many ways. However, it is recommended that both course facilitator (teacher) and course participants (students) have at least some experience with the Assignment module before the Workshop is used in the course.<br />
<br />
* As in the Assignment, course participants submit their work during the Workshop activity. Every course participant submits their own work. The submission may consist of a text and attachments. Therefore, Workshop submission merges both ''Online text'' and ''Upload file'' types of the Assignment module. Support for team work (in the sense of one submission per group of participants) is out of scope of Workshop module.<br />
* The submissions are assessed using a structured assessment form defined by the course facilitator (teacher). Workshop supports several types of assessment forms. All of them allows multi-criteria assessment - on the contrary to the Assignment module where only one grade is given to a submission.<br />
* Workshop supports peer assessment process. Course participants may be asked to assess selected set of their peers' submissions. The module coordinates the collection and distribution of these assessments.<br />
* Course participants get actually two grades in a single Workshop activity - grade for their submission (that is how good their submitted work is) and grade for assessment (that is how well they assessed their peers). Workshop activity creates two grade items in the course [[Gradebook]] and they can be aggregated there as needed (in Moodle 1.x, Workshop automatically summed up these grades and sent the total into Gradebook as a single item).<br />
* The process of peer assessment and understanding the assessment form can be trained in advance on so called example submissions. These examples are provided by the facilitator together with a reference assessment. Workshop participants can assess these examples and compare their assessment with the reference one.<br />
* The course facilitator can select some submissions and publish them so they are available to the others at the end of Workshop activity (on contrary to the Assignment module where submitted work is available only to the author and the facilitator).<br />
<br />
== Workshop phases ==<br />
<br />
Typical Workshop is not a short-term activity and it takes up to several days or even weeks to complete. The worflow is divided into five phases. Course facilitator switches the activity from one phase to another manually, there is no support for automatic scheduled switching yet. It is possible to switch from any phase to any other. The most typical scenario is switching in linear way from the first phase to the last one. However, advanced recursive model is possible, too.<br />
<br />
The progress of the activity is visualised in so called Workshop planner tool. It displays all Workshop phases and highlight the current one. It also lists all the tasks the user has in the current phase with the information of whether the task is finished or not yet finished or even failed.<br />
<br />
=== Setup phase ===<br />
<br />
In this initial phase, Workshop participants cannot do anything (neither modify their submissions nor their assessments). Course facilitators use this phase to change workshop settings, modify the grading strategy of tweak assessment forms. You can switch to this phase any time you need to change the Workshop setting and prevent users from modifying their work.<br />
<br />
=== Submission phase ===<br />
<br />
In the submission phase, Workshop participants submit their work. Access control dates can be set so that even if the Workshop is in this phase, submitting can be allowed in the given time frame only. Submission start date (and time), submission end date (and time) or both can be specified.<br />
<br />
=== Assessment phase ===<br />
<br />
If the Workshop uses peer assessment feature, this is the phase when Workshop participants assess the submissions allocated to them for the review. As in the submission phase, access can be controlled by specified date and time since when and/or until when the assessment is allowed.<br />
<br />
=== Grading evaluation phase ===<br />
<br />
The major task during this phase is to calculate the final grades for submissions and for assessments and provide feedback for authors and reviewers. Workshop participants cannot modify their submissions or their assessments in this phase any more. Course facilitators can manually override the calculated grades. Also, selected submissions can be set as published so they become available to all Workshop participants in the next phase.<br />
<br />
=== Closed ===<br />
<br />
Whenever the Workshop is being switched into this phase, the final grades calculated in the previous phase are pushed into the course Gradebook. This will result in the Workshop grades appearing in the Gradebook. Participants may view their submissions, their submission assessments and eventually other published submissions in this phase.<br />
<br />
== Grading strategies ==<br />
<br />
Simply said, selected grading strategy determines how the assessment form may look like and how the final grade for submission is calculated from all the filled assessment forms for the given submission. Workshop ships with four standard grading strategies. More strategies can be developed as pluggable extensions.<br />
<br />
=== Accumulative grading strategy ===<br />
<br />
In this case, the assessment form consists of a set of criteria. Each criteria is graded separately using either a number grade (eg out of 100) or a scale (using either one of site-wide scale or a scale defined in a course). Each criterion can have its weight set. Reviewers can put comments to all assessed criteria.<br />
<br />
When calculating the total grade for the submission, the grades for particular criteria are firstly normalized to a range from 0% to 100%. Then the total grade by a given assessment is calculated as weighted mean of normalized grades. Scales are considered as grades from 0 to M-1, where M is the number of scale items.<br />
<br />
: <math>G_s = \frac{\sum_{i=1}^N \frac{g_i}{max_i} w_i }{\sum_{i=1}^N w_i}</math><br />
: where <math>g_i \in \mathbb{N}</math> is the grade given to the i-th criterion, <math>max_i \in \mathbb{N}</math> is the maximal possible grade of the i-th criterion, <math>w_i \in \mathbb{N} </math> is the weight of the i-th criterion and <math>N \in \mathbb{N} </math> is the number of criteria in the assessment form.<br />
<br />
It is important to realize that the influence of a particular criterion is determined by its weight only, not the grade type or range used. Let us have three criteria in the form, first using 0-100 grade, the second 0-20 grade and the third using a three items scale. If they all have the same weight, then giving grade 50 in the first criteria has the same impact as giving grade 10 for the second criteria.<br />
<br />
=== Comments ===<br />
<br />
The assessment form is similar to the one used in accumulative grading strategy but no grades can be given, just comments. The total grade for the assessed submission is always set to 100%. This strategy can be effective in repetitive workflows when the submissions are firstly just commented by reviewers to provide initial feedback to the authors. Then Workshop is switched back to the submission phase and the authors can improve it according the comments. Then the grading strategy can be changed to a one using proper grading and submissions are assessed again using different assessment form.<br />
<br />
=== Number of errors ===<br />
<br />
In Moodle 1.x, this was called Error banded strategy. The assessment form consists of several assertions, each of them can be marked as passed or failed by the reviewer. Various words can be set to express the pass or failure state - eg Yes/No, Present/Missing, Good/Poor, etc.<br />
<br />
The grade given by a particular assessment is calculated from the weighted count of negative assessment responses (failed assertions). Here, the ''weighted count'' means that a response with weight <math>w_i</math> is counted <math>w_i</math>-times. Course facilitators define a mapping table that converts the number of failed assertions to a percent grade for the given submission. Zero failed assertion is always mapped to 100% grade.<br />
<br />
This strategy may be used to make sure that certain criteria were addressed in the submission. Examples of such assessment assertions are: ''Has less than 3 spelling errors'', ''Has no formatting issues'', ''Has creative ideas'', ''Meets length requirements'' etc. This assessment method is considered as easier for reviewers to understand and deal with. Therefore it is suitable even for younger participants or those just starting with peer assessment, while still producing quite objective results.<br />
<br />
=== Rubric ===<br />
<br />
See [http://en.wikipedia.org/wiki/Rubric_(academic) the description] of this scoring tool at Wikipedia. The rubric assessment form consists of a set of criteria. For each criterion, several ordered descriptive levels is provided. A number grade is assigned to each of these levels. The reviewer chooses which level answers/describes the given criterion best.<br />
<br />
The final grade is aggregated as<br />
<br />
: <math>G_s = \frac{\sum_{i=1}^N g_i }{\sum_{i=1}^N max_i}</math><br />
: where <math>g_i \in \mathbb{N}</math> is the grade given to the i-th criterion, <math>max_i \in \mathbb{N}</math> is the maximal possible grade of the i-th criterion and <math>N \in \mathbb{N} </math> is the number of criterions in the rubric.<br />
<br />
Example of a single criterion can be: ''Overall quality of the paper'' with the levels ''5 - An excellent paper'', ''3 - A mediocre paper'', ''0 - A weak paper'' (the number represent the grade).<br />
<br />
There are two modes how the assessment form can be rendered - either in common grid form or in a list form. It is safe to switch the representation of the rubric any time and it is better to actually try it than to read a description here :-)<br />
<br />
'''Note on backwards compatibility:''' This strategy merges the legacy Rubric and Criterion strategies from Moodle 1.x into a single one. Conceptually, legacy Criterion was just one dimension of Rubric. In Workshop 1.x, Rubric could have several criteria (categories) but were limited to a fixed scale with 0-4 points. On the other hand, Criterion strategy in Workshop 1.9 could use custom scale, but was limited to a single aspect of assessment. The new Rubric strategy combines the old two. To mimic the legacy behaviour, the old Workshop are automatically upgraded so that:<br />
<br />
* Criterion strategy from 1.9 are replaced with Rubric 2.0 using just one dimension<br />
* Rubric from 1.9 are by Rubric 2.0 by using point scale 0-4 for every criterion.<br />
<br />
In Moodle 1.9, reviewer could suggest an optional adjustment to a final grade. This is not supported any more. Eventually this may be supported in the future versions again as a standard feature for all grading strategies, not only rubric.<br />
<br />
== Calculation of final grades ==<br />
<br />
The final grades for a Workshop activity are obtained gradually at several stages. The following scheme illustrates the process and also provides the information in what database tables the grade values are stored.<br />
<br />
[[Image:workshop_grades_calculation.png|400px|thumb|left|The scheme of grades calculation in Workshop]]<br />
<br clear="all"/><br />
<br />
As you can see, every participant gets two numerical grades into the course Gradebook. During the Grading evaluation phase, course facilitator can let Workshop module to calculate these final grades. Note that they are stored in Workshop module only until the activity is switched to the final (Closed) phase. Therefore it is pretty safe to play with grades unless you are happy with them and then close the Workshop and push the grades into the Gradebook. You can even switch the phase back, recalculate or override the grades and close the Workshop again so the grades are updated in the Gradebook again (should be noted that you can override the grades in the Gradebook, too).<br />
<br />
During the grading evaluation, Workshop grades report provides you with a comprehensive overview of all individual grades. The report uses various symbols and syntax:<br />
<br />
{| class="nicetable"<br />
|-<br />
! Value<br />
! Meaning<br />
|-<br />
| - (-) < Alice<br />
| The is an assessment allocated to be done by Alice, but it has been neither assessed nor evaluated yet<br />
|-<br />
| 68 (-) < Alice<br />
| Alice assessed the submission, giving the grade for submission 68. The grade for assessment (grading grade) has not been evaluated yet.<br />
|-<br />
| 23 (-) > Bob<br />
| Bob's submission was assessed by a peer, receiving the grade for submission 23. The grade for this assessment has not been evaluated yet.<br />
|-<br />
| 76 (12) < Cindy<br />
| Cindy assessed the submission, giving the grade 76. The grade for this assessment has been evaluated 12.<br />
|-<br />
| 67 (8) @ 4 < David<br />
| David assessed the submission, giving the grade for submission 67, receiving the grade for this assessment 8. His assessment has weight 4<br />
|-<br />
| 80 (<del>20</del> / <ins>17</ins>) > Eve<br />
| Eve's submission was assessed by a peer. Eve's submission received 80 and the grade for this assessment was calculated to 20. Teacher has overridden the grading grade to 17, probably with an explanation for the reviewer.<br />
|}<br />
<br />
=== Grade for submission ===<br />
<br />
The final grade for every submission is calculated as weighted mean of particular assessment grades given by all reviewers of this submission. The value is rounded to a number of decimal places set in the Workshop settings form.<br />
<br />
Course facilitator can influence the grade for a given submission in two ways:<br />
<br />
* by providing their own assessment, possibly with a higher weight than usual peer reviewers have<br />
* by overriding the grade to a fixed value<br />
<br />
=== Grade for assessment ===<br />
<br />
Grade for assessment tries to estimate the quality of assessments that the participant gave to the peers. This grade (also known as ''grading grade'') is calculated by the artificial intelligence hidden within the Workshop module as it tries to do typical teacher's job.<br />
<br />
During the grading evaluation phase, you use a Workshop subplugin to calculate grades for assessment. At the moment, only one subplugin is available called ''Comparison with the best assessment''. The following text describes the method used by this subplugin. Note that more grading evaluation subplugins can be developed as Workshop extensions.<br />
<br />
Grades for assessment are displayed in the braces () in the Workshop grades report. The final grade for assessment is calculated as the average of particular grading grades.<br />
<br />
There is not a single formula to describe the calculation. However the process is deterministic. Workshop picks one of the assessments as the ''best'' one - that is closest to the mean of all assessments - and gives it 100% grade. Then it measures a 'distance' of all other assessments from this best one and gives them the lower grade, the more different they are from the best (given that the best one represents a consensus of the majority of assessors). The parameter of the calculation is how strict we should be, that is how quickly the grades fall down if they differ from the best one.<br />
<br />
If there are just two assessments per submission, Workshop can not decide which of them is 'correct'. Imagine you have two reviewers - Alice and Bob. They both assess Cindy's submission. Alice says it is a rubbish and Bob says it is excellent. There is no way how to decide who is right. So Workshop simply says - ok, you both are right and I will give you both 100% grade for this assessment. To prevent it, you have two options:<br />
<br />
* Either you have to provide an additional assessment so the number of assessors (reviewers) is odd and workshop will be able to pick the best one. Typically, the teacher comes and provide their own assessment of the submission to judge it<br />
* Or you may decide that you trust one of the reviewers more. For example you know that Alice is much better in assessing than Bob is. In that case, you can increase the weight of Alice's assessment, let us say to "2" (instead of default "1"). For the purposes of calculation, Alice's assessment will be considered as if there were two reviewers having the exactly same opinion and therefore it is likely to be picked as the best one.<br />
<br />
'''Backward compatibility note:''' In Workshop 1.x this case of exactly two assessors with the same weight is not handled properly and leads to wrong results as only the one of them is lucky to get 100% and the second get lower grade.<br />
<br />
It is very important to know that the grading evaluation subplugin ''Comparison with the best assessment'' does not compare the final grades. Regardless the grading strategy used, every filled assessment form can be seen as n-dimensional vector or normalized values. So the subplugin compares responses to all assessment form dimensions (criteria, assertions, ...). Then it calculates the distance of two assessments, using the variance statistics.<br />
<br />
To demonstrate it on example, let us say you use grading strategy Number of errors to peer-assess research essays. This strategy uses a simple list of assertions and the reviewer (assessor) just checks if the given assertion is passed or failed. Let us say you define the assessment form using three criteria:<br />
<br />
# Does the author state the goal of the research clearly? (yes/no)<br />
# Is the research methodology described? (yes/no)<br />
# Are references properly cited? (yes/no)<br />
<br />
Let us say the author gets 100% grade if all criteria are passed (that is answered "yes" by the assessor), 75% if only two criteria are passed, 25% if only one criterion is passed and 0% if the reviewer gives 'no' for all three statements.<br />
<br />
Now imagine the work by Daniel is assessed by three colleagues - Alice, Bob and Cindy. They all give individual responses to the criteria in order:<br />
<br />
* Alice: yes / yes / no<br />
* Bob: yes / yes / no<br />
* Cindy: no / yes / yes<br />
<br />
As you can see, they all gave 75% grade to the submission. But Alice and Bob agree in individual responses, too, while the responses in Cindy's assessment are different. The evaluation method ''Comparison with the best assessment'' tries to imagine, how a hypothetical absolutely fair assessment would look like. In the [[Development:Workshop 2.0 specification]], David refers to it as "how would Zeus assess this submission?" and we estimate it would be something like this (we have no other way):<br />
<br />
* Zeus 66% yes / 100% yes / 33% yes<br />
<br />
Then we try to find those assessments that are closest to this theoretically objective assessment. We realize that Alice and Bob are the best ones and give 100% grade for assessment to them. Then we calculate how much far Cindy's assessment is from the best one. As you can see, Cindy's response matches the best one in only one criterion of the three so Cindy's grade for assessment will not be much high.<br />
<br />
The same logic applies to all other grading strategies, adequately. The conclusion is that the grade given by the best assessor does not need to be the one closest to the average as the assessment are compared at the level of individual responses, not the final grades.<br />
<br />
=== More explanations ===<br />
<br />
* [http://moodle.org/mod/forum/discuss.php?d=153268 Thread at moodle.org] where David explains a particular Workshop results<br />
* [http://www.slideshare.net/mark.drechsler/moodle-workshop-20-a-simplified-explanation Presentation by Mark Drechsler]<br />
<br />
== Research papers dealing with Workshop module ==<br />
<br />
* [http://portal.acm.org/citation.cfm?id=1562877.1562985 Peer assessments using the moodle workshop tool] by John F. Dooley<br />
* [http://fie-conference.org/fie2009/papers/1254.pdf Easy-to-use Workshop Module] by Álvaro Figueira and Elisabete Cunha<br />
<br />
== For developers ==<br />
<br />
Please see [[Development:Workshop]] for more information on the module infrastructure and ways how to extend provided functionality by developing own Workshop subplugins.<br />
<br />
== See also ==<br />
<br />
* [http://moodlefairy.posterous.com/a-brief-journey-into-the-moodle-20-workshop A Brief Journey into the Moodle 2.0 Workshop] at moodlefairy's posterous<br />
* [[Workshop module/Tutorial]]<br />
* [http://download.moodle.org/download.php/docs/en/using_moodle/ch6_workshops.pdf Using Moodle Chapter 6: Workshops]<br />
* [http://www2.oakland.edu/elis/traindocs/Moodle/Workshop/index.html Moodle Workshop Guide] by Laura M. Christensen &copy; 2007<br />
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=74784 New Workshop Module] forum discussion<br />
* [http://www.slideshare.net/nrparmar/moodle-workshop-case-study-1807686 Promoting Peer Assessment: Moodle Workshop] by Nitin Parmar, 2006<br />
* [[Exercise module]] allows student self assessment and teacher to separately grade the quality of the assignment and the self assessment.<br />
<br />
[[Category:Workshop]]<br />
[[Category:Contributed code]]<br />
<br />
[[de:Workshop]]<br />
[[cs:Modul Workshop]]<br />
[[fr:Atelier]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Roles&diff=45793Development:Roles2008-10-26T10:00:15Z<p>Delius: /* The existing system */ Changed title</p>
<hr />
<div>{{Moodle 1.7}}<br />
'''Roles and permissions''' is in Moodle 1.7 onwards.<br />
<br />
==Definitions==<br />
<br />
A role is an identifier of the user's status in some context. For example: Teacher, Student and Forum moderator are examples of roles.<br />
<br />
A capability is a description of some particular Moodle feature. Capabilities are associated with roles. For example, ''mod/forum:replypost'' is a capability.<br />
<br />
A permission is some value that is assigned for a capability for a particular role. For example, allow or prevent.<br />
<br />
A context is a "space" in the Moodle, such as courses, activity modules, blocks etc.<br />
<br />
==The system prior to v1.7==<br />
<br />
In versions prior to v1.7, Moodle uses a fixed set of roles i.e. primary admin, admins, course creators, editing teachers, non-editing teachers, students, and guests. For each role, the capability or actions that they can perform are fixed. For example, the role student allows the user to submit an assignment, but doesn't allow the user to browse/edit other users' work. By using this setup we limit ourselves to a rather rigid set of capabilities for each role. If we want, say a particular student or group to be able to mark assignments in a particular course, we can't do that without giving these users teacher privileges.<br />
<br />
==The new roles and capability system==<br />
<br />
With v1.7 and greater, Moodle introduces a roles and capabilities system.<br />
<br />
Role has two primary functions:<br />
# define list of permissions - role definition is global for all contexts, but can be changed by local context overrides<br />
# replace old course enrolments - role assignment in course context is similar to the old enrolment process<br />
<br />
The new system will allow authorized users to define an arbitrary number of roles (eg a teacher) <br />
<br />
A role consists of a list of permissions for different possible actions within Moodle (eg delete discussions, add activities etc)<br />
<br />
Roles can be applied to users in a context (eg assign Fred as a teacher in a particular course)<br />
<br />
Here are the possible contexts, listed from the most general to the most specific. <br />
<br />
[[Image:Moodle-contexts-1.8.png|right|thumbnail|200px|A diagram of the contexts in Moodle. Click on the diagram to see a more detailed view of it.]]<br />
<br />
#CONTEXT_SYSTEM -- the whole site<br />
#CONTEXT_USER -- another user<br />
#CONTEXT_COURSECAT -- a course category<br />
#CONTEXT_COURSE -- a course<br />
#CONTEXT_MODULE -- an activity module<br />
#CONTEXT_BLOCK -- a block<br />
<br />
Please note that CONTEXT_PERSONAL (present in 1.7-1.8) was never implemented and was removed in 1.9. CONTEXT_GROUP is also not implemented and can not be used.<br />
<br />
An authorized user will be able to assign an arbitrary number of roles to each user in any context.<br />
<br />
Capabilities can have the following permissions:<br />
<br />
#CAP_INHERIT<br />
#CAP_ALLOW<br />
#CAP_PREVENT<br />
#CAP_PROHIBIT<br />
<br />
If no permission is defined, then the capability permission is inherited from a context that is more general than the current context. If we define different permission values for the same capability in different contexts, we say that we are overriding the capability in the more specific context.<br />
<br />
Since the capabilities in each role could be different, there could be conflict in capabilities. This is resolved by enforcing the rule that the capability defined for a more specific context will win, unless a prohibit is encountered in a less specific context.<br />
<br />
For example, Mark has a student role at course level, which allows him to write into a wiki. But Mark also got assigned a Visitor role at a module context level (for a particular wiki) which prevents him from writing to the wiki (read only). Therefore, for this particular wiki, Mark will not be able to write to the wiki since the more specific context wins.<br />
<br />
If we set a PROHIBIT on a capability, it means that the capability cannot be overridden and will ALWAYS have a permission of prevent (deny). Prohibit always wins. For example, Jeff has a naughty student role that prohibits him from postings in any forums (for the whole site), but he's also assigned a facilitator role in "Science forum" in the course Science and Math 101. Since prohibit always wins, Jeff is unable to post in "Science forum".<br />
<br />
Allow and prevent will cancel each other out if set for the same capability at the same context level. If this happens, we refer to the previous context level to determine the permission for the capability.<br />
<br />
This may sound more complex than it really is in practice. The upshot is that the system can be flexible enough to allow pretty much any combination of permissions.<br />
<br />
===Capability-locality changes in v1.9===<br />
<br />
When resolving conflicts between "allow" and "prevent" in v1.7 and v1.8 the locality of the capability is taken into account, although with less weight than the locality of the role assignment. In v1.9 the process has been simplified, we consider locality of the role assignment when dealing with allow/prevent conflicts, but ignore where the capability has been defined (as long as it applies to the context).<br />
<br />
For example - for the situation where there is<br />
<br />
* two roles assigned to one user in a context (eg student role and teacher role)<br />
* one override on one of those roles ( eg student role), at the same context<br />
<br />
then<br />
<br />
* '''1.7/1.8''' The override used to ''always'' win over the settings from the combined roles.<br />
<br />
* '''1.9''' The override is combined with the student role first. and then the roles are combined. This is more logical, as the override is acting like a modification to the student role.<br />
<br />
For more details, see [http://tracker.moodle.org/browse/MDL-11218 MDL-11218]<br />
<br />
==Upgrading from 1.6==<br />
<br />
A smooth upgrade will be provided with 1.7. The existing roles (admin, teacher, student, etc), and the existing capabilities will be automatically retained. This is done by creating default roles at site/course levels, and assigning the current users to these roles accordingly. The default roles will have default capabilities associated with them, mirroring what we have in 1.6. With no modifications, Moodle will operate exactly the same before and after the upgrade.<br />
<br />
===Admins===<br />
<br />
Admin users will be assigned the default legacy admin role in the system (site) context<br />
<br />
===Course Creators===<br />
<br />
Course Creators will be assigned the default legacy course creator role in the system (site) context<br />
<br />
===Teachers===<br />
<br />
Users who were teachers will be assigned the default legacy teacher role (or non-editing teacher role) in all courses they were teacher.<br />
<br />
===Students===<br />
<br />
Users who were students will be assigned the default student role in all courses they were student.<br />
<br />
===Guests===<br />
<br />
There will still be a single guest user with no default role at site level. For each course that allows guest access, the guest role will be assigned to the guest user for that course context. The guest control for the course will be modified from three to two options (guests always need to enter enrolment key - on/off). This setting is checked as now to force guests to enter key.<br />
<br />
==Capabilities==<br />
<br />
This will be a comprehensive list of capabilities (it's not complete yet). It is important that capability names are unique.<br />
<br />
===Core-level Capabilities===<br />
<br />
Moodle core capability names start with 'moodle/'. The next word indicates what type of core capability it is, and the last word is the actual capability itself. The capabilities for the Moodle core are defined in lib/db/access.php<br />
<br />
#moodle/legacy:guest - legacy capabilities are used to transition existing users to the new roles system during the upgrade to Moodle 1.7<br />
#moodle/legacy:student<br />
#moodle/legacy:teacher<br />
#moodle/legacy:editingteacher<br />
#moodle/legacy:coursecreator<br />
#moodle/legacy:admin<br />
#moodle/site:doanything - special capability, meant for admins, if is set, overrides all other capability settings<br />
#moodle/site:config - applicable in admin/index.php and config.php (might break down later) : 1)admin/config.php 2)admin/configure.php 3)blocks/admin/block_admin.php load_content_for_site()<br />
#moodle/site:readallmessages - reads all messages and history<br />
#moodle/site:approvecourse - approves a pending course<br />
#moodle/site:manageblocks - adding/removing/editing blocks (site, course contexts only for now) : 1)_add_edit_controls moodleblock.class.php <br />
#moodle/site:backup - can create a course backup : 1)course/category.php 2)block_admin.php<br />
#moodle/site:restore - can restore into this context : 1)course/category.php 2)block_admin.php<br />
#moodle/site:import - can import other courses into this context : 1)block_admin.php<br />
#moodle/site:accessallgroups - able to access all groups irrespective of what group the user is in<br />
#moodle/site:accessdb - directly accessing db (phpmyadmin)<br />
#moodle/site:viewfullnames - able to see fullnames of other users<br />
#moodle/site:viewparticipants - able to view participants<br />
#moodle/site:viewreports - able to view site/course reports<br />
#moodle/site:trustcontent - ability to use trusttext feature and bypass cleaning in specific areas<br />
#moodle/site:uploadusers - ability to upload/update users from text file; moodle/role:assign capability is needed for course enrolling<br />
#moodle/blog:view - read blogs (usable in system or course context)<br />
#moodle/blog:create - write new blog posts (usable in system context only)<br />
#moodle/blog:manageofficialtags - create/delete official blog tags that others can use (usable in system context only)<br />
#moodle/blog:managepersonaltags - delete personal blog tags that others can use (usable in system context only) Note: users can always add own personal tags. This setting should be off for students by default.<br />
#moodle/blog:manageentries - edit/delete all blog entries (usable in system context only)<br />
#moodle/course:setcurrentsection - mark course section<br />
#moodle/course:create - create courses : 1)course/edit.php 2)course/category.php 3)course/index.php<br />
#moodle/course:delete - create courses : 1)course/category.php<br />
#moodle/course:update - update course settings<br />
#moodle/course:view - can use this to find participants<br />
#moodle/course:viewparticipants - allows a user to view participant list<br />
#moodle/course:viewscales - view scales (i.e. in a help window?) : 1)course/scales.php<br />
#moodle/course:manageactivities - adding/removing/editing activities and resources (don't think it makes any sense to split these)<br />
#moodle/course:managescales - add, delete, edit scales, move scales up and down : 1)blocks/block_admin.php 2)course/scales.php<br />
#moodle/course:managegroups - managing groups, add, edit, delete : 1)course/groups.php 2)course/group.php<br />
#moodle/course:managefiles - manage course files and folders<br />
#moodle/course:managequestions - manage course questions<br />
#moodle/course:managemetacourse - manage child courses in metacourse<br />
#moodle/course:reset - able to reset the course<br />
#moodle/course:useremail - Can use the enable/disable email stuff<br />
#moodle/course:visibility - hide/show courses : 1)course/category.php<br />
#moodle/course:viewhiddencourses - see hidden courses<br />
#moodle/course:activityvisibility - hide/show activities within a course<br />
#moodle/course:viewhiddenactivities - able to see activities that have been hidden<br />
#moodle/course:sectionvisibility - hide/show sections<br />
#moodle/course:viewhiddensections - view hidden sections<br />
#moodle/course:viewcoursegrades - views all grades in course<br />
#moodle/course:viewhiddenuserfields - view all hidden user fields<br />
#moodle/course:managegrades - manages grades settings in course<br />
#moodle/category:create - create category : 1)course/index.php<br />
#moodle/category:delete - delete category : 1)course/index.php<br />
#moodle/category:update - update category settings (sort and rename) this is currently an admin capability : 1)course/category.php<br />
#moodle/category:visibility - hide/show categories : 1)course/index.php<br />
#moodle/user:viewusergrades - view your own, or other user's grades (with specified context)<br />
#moodle/user:create - create user : 1) user/edit.php<br />
#moodle/user:delete - delete user : 1) admin/user.php<br />
#moodle/user:readuserblogs - read blog entries<br />
#moodle/user:update - update user settings : 1) user/edit.php<br />
#moodle/user:viewdetails - view personally-identifying user details (e.g. name, photo).<br />
#moodle/user:viewhiddendetails - view user details marked as "hidden"<br />
#moodle/calendar:manageownentries - create/edit/delete <br />
#moodle/calendar:manageentries - create/edit/delete<br />
#moodle/role:assign - assign roles to users<br />
#moodle/role:override - can override role capabilities (depending on context)<br />
#moodle/role:manage - create/edit/delete roles, set capability permissions for each role<br />
#moodle/role:unassignself - unassign yourself from your own roles<br />
#moodle/role:viewhiddenassigns - view role assignments that have been marked as hidden<br />
#moodle/question:import - imports questions (course level?) - Yes, question permissions currently need to be course-level.--[[User:Tim Hunt|Tim Hunt]]<br />
#moodle/question:export - exports questions (course level?)<br />
#moodle/question:managecategory - add/delete/edit question categories (course level?)<br />
#moodle/question:manage - add/edit/delete a question (course level)<br />
<br />
===User-level Capabilities===<br />
# moodle/user:readuserposts -read individual user posts on profile page (parent?)<br />
# moodle/user:readuserblogs -read individual user blogs on profile page (parent?)<br />
# moodle/user:viewuseractivitiesreport-read individual activity report on profile page (parent?)<br />
# moodle/user:editprofile - edit profile (normally used in CONTEXT_USERID and CONTEXT_SYSTEM)<br />
<br />
===Module-level Capabilities===<br />
The capabilities are cached into a database table when a module is installed or updated. Whenever the capability definitions are updated, the module version number should be bumped up so that the database table can be updated.<br />
<br />
The naming convention for capabilities that are specific to modules and blocks is 'mod/mod_name:capability'. The part before the colon is the full path to the module in the Moodle code. The module capabilities are defined in mod/mod_name/db/access.php.<br />
<br />
#Assignment<br />
##mod/assignment:view- reading the assignment description<br />
##mod/assignment:submit - turn assignment in<br />
##mod/assignment:grade - grading, viewing of list of submitted assignments<br />
#Chat<br />
##mod/chat:chat - allows a user to participate in this chat<br />
##mod/chat:readlog - allows a user to read past chat session logs<br />
##mod/chat:deletelog - allows a user to delete past chat logs<br />
#Choice<br />
##mod/choice:choose - make a choice<br />
##mod/choice:readresponses - read all responses<br />
##mod/choice:deleteresponses - deletes all responses<br />
##mod/choice:downloadresponses - download responses<br />
#Database<br />
##mod/data:viewentry - reads other people's entry<br />
##mod/data:writeentry - add / edit and delete (own) entries<br />
##mod/data:managetemplates - add, delete, edit fields and templates<br />
##mod/data:manageentries - edit/delete all entries<br />
##mod/data:comment - comment<br />
##mod/data:managecomments - edit/delete all comments<br />
##mod/data:rate - rate an entry<br />
##mod/data:viewrating<br />
##mod/data:approve - approves an entry<br />
##mod/data:uploadentries - batch upload of entries<br />
#Exercise<br />
##mod/exercise:assess<br />
#Forum<br />
##mod/forum:viewdiscussion<br />
##mod/forum:viewdiscussionsfromallgroups<br />
##mod/forum:viewhiddentimedposts<br />
##mod/forum:startdiscussion<br />
##mod/forum:replypost<br />
##mod/forum:viewrating<br />
##mod/forum:viewanyrating<br />
##mod/forum:rate<br />
##mod/forum:createattachment<br />
##mod/forum:deleteownpost<br />
##mod/forum:deleteanypost<br />
##mod/forum:splitdiscussions<br />
##mod/forum:movediscussions<br />
##mod/forum:editanypost<br />
##mod/forum:viewqandawithoutposting<br />
##mod/forum:viewsubscribers<br />
##mod/forum:managesubscriptions<br />
##mod/forum:throttlingapplies<br />
#Glossary<br />
##mod/glossary:write - add entries<br />
##mod/glossary:manageentries - add, edit, delete entries<br />
##mod/glossary:managecategories - create, delete, edit categories<br />
##mod/glossary:comment - comment on an entry<br />
##mod/glossary:managecomments - edit, delete comments<br />
##mod/glossary:import - import glossaries<br />
##mod/glossary:export - export glossaries<br />
##mod/glossary:approve - approve glossaries<br />
##mod/glossary:rate - rates glossary<br />
##mod/glossary:viewrating - view ratings<br />
#Hotpot<br />
##mod/hotpot:attempt - attempt a hotpot<br />
##mod/hotpot:viewreport - review and view reports<br />
##mod/hotpot:grade - (grade? and) regrade<br />
##mod/hotpot:deleteattempt - deletes attempts<br />
#Label<br />
##none<br />
#Lams<br />
##mod/lams:participate - original student<br />
##mod/lams:manage - original teacher<br />
#Lesson<br />
##mod/lesson:edit - add and edit pages<br />
##mod/lesson:manage - view student attempts<br />
#Quiz<br />
##mod/quiz:grade - comment, override grade, manual grade<br />
##mod/quiz:preview - previews the quiz<br />
##mod/quiz:viewreports - view quiz result reports<br />
##mod/quiz:manage - add/delete/move (up or down) questions for a quiz<br />
##mod/quiz:attempt - attempt the quiz--[[User:Tim Hunt|Tim Hunt]]<br />
#Resource<br />
#Scorm<br />
##mod/scorm:viewgrades<br />
#Survey<br />
##mod/survey:download - downloads survery result<br />
##mod/survey:participate - participate/ do survey<br />
##mod/survey:readresponses - read all user's responese<br />
#Wiki<br />
##mod/wiki:participate - original student, meaning depends of type and course setting<br />
##mod/wiki:manage - original teacher, manages assigned group; moodle/site:accessallgroups is needed to manage all groups <br />
##(Waiting on new wiki)<br />
#Workshop<br />
##mod/workshop:participate - original student, allows user to submit and assess<br />
##mod/workshop:manage - original teacher, user can manage others<br />
##(Waiting on new Workshop)<br />
<br />
===Enrolment-level Capabilities===<br />
<br />
The naming convention for capabilities that are specific to enrolment is 'enrol/enrol_name:capability'. The enrolment capabilities are defined in enrol/enrol_name/db/access.php.<br />
<br />
#Authorize.net Payment Gateway <br />
##enrol/authorize:managepayments - manage user payments, capture, void, refund, delete etc.<br />
<br />
===Blocks===<br />
#activity_modules<br />
##None<br />
#admin<br />
#admin_2<br />
#admin_bookmarks<br />
#blog_menu<br />
#blog_tags<br />
#calendar_month<br />
#calendar_upcoming<br />
#course_list<br />
#course_summary<br />
#glossary_random<br />
#html<br />
#loancalc<br />
#login<br />
#messages<br />
#news_items<br />
#online_users<br />
#participants<br />
#quiz_results<br />
#recent_activity<br />
#rss_client<br />
##block/rss_client:createprivatefeeds<br />
##block/rss_client:createsharedfeeds<br />
##block/rss_client:manageownfeeds<br />
##block/rss_client:manageanyfeeds<br />
#search<br />
#search_forums<br />
#section_links<br />
#site_main_menu<br />
#social_activities<br />
<br />
===Questions===<br />
I am adding question categories here because they seem to have been forgotten in the whole scheme of things since having been removed from the quiz module itself. I've made a suggestion on how these could be handled in [http://www.moodle.org/bugs/bug.php?op=show&bugid=6118&pos= bug 6118].<br />
<br />
See [http://moodle.org/mod/forum/discuss.php?d=51143 this forum thread] for a discussion about the current problems wth publishing question categories.[[User:Tim Hunt|Tim Hunt]] 18:50, 8 August 2006 (WST)<br />
<br />
==Programming Interface==<br />
<br />
Although the Roles system may look complicated at first glance, implementing it in Moodle code is fairly simple.<br />
<br />
* You need to define each capability once, so that Moodle can upgrade existing roles to take advantage of it. You do this in an access.php inside the db folder of any module (eg see mod/forum/db/access.php). The array contains entries like this (note the descriptions for the legacy roles which provides forward compatibility):<br />
'mod/forum:viewforum' => array(<br />
'captype' => 'read',<br />
'contextlevel' => CONTEXT_MODULE,<br />
'legacy' => array(<br />
'guest' => CAP_PREVENT,<br />
'student' => CAP_ALLOW,<br />
'teacher' => CAP_ALLOW,<br />
'editingteacher' => CAP_ALLOW,<br />
'coursecreator' => CAP_ALLOW,<br />
'admin' => CAP_ALLOW<br />
)<br />
),<br />
* To load/change these capabilities you need to bump the module version. There's no need to provide changes or differences as Moodle will scan the whole array and sort it out.<br />
* On each page you need to find the context the user is working in, using the get_context_instance() function. For example, in the forum module:<br />
<br />
$context = get_context_instance(CONTEXT_MODULE, $cm->id);<br />
* or to at the course level:<br />
$context = get_context_instance(CONTEXT_COURSE, $id);<br />
* Then, whenever you want to check that the current user has rights to do something, call has_capability() like this:<br />
if (!has_capability('mod/forum:viewforum', $context)) {<br />
print_error('nopermissiontoviewforum');<br />
}<br />
* If you just want to assert a capability and then finish with an error message if it's not met (as we did above), then a shorter way it to use require_capability() like this:<br />
<br />
require_capability('mod/forum:viewforum', $context);<br />
<br />
* Note that there are extra parameters you can specify to get a custom error message, otherwise users get an automated "No permissions" message that lists the permission they were missing.<br />
<br />
<br />
As a result of the new Roles System, all calls to isadmin(), iscoursecreator, isteacheredit(), isteacher(), isstudent(), and isguest() will have to be replaced with calls to has_capability() or require_capability(). However, these functions will be retained for some backward compatibility with old code, using the legacy capabilities to try and work out what to do.<br />
<br />
==Metacourses==<br />
<br />
The behaviour of metacourses in Moodle 1.7 changed slightly, in that where it used to just synch students from child courses to the parent course, it will now synch ALL roles. Teachers etc of the child courses will have the same role in the meta course. Technically metacourse synchronises all role assignments in CONTEXT_COURSE with its child courses; the only exception are users with moodle/course:managemetacourse capability, these users are synchronized only upwards, they are not unenrolled from metacourse when unenroling from child course or when removing the child from metacourse.<br />
<br />
In order to import/enrol other courses into metacourse you need to have moodle/course:managemetacourse capability. You can add manually only participants with moodle/course:managemetacourse, all other participants are automatically synced with child courses - if you try to manually enrol user without this capability error is displayed. Similar error is shown also when you try to manually unenrol participant from meta course while still being enrolled in child course.<br />
<br />
Sample setup:<br />
* metacourse manager has been assigned role with moodle/course:managemetacourse capability in system or course category context<br />
* students are enrolled in several child courses<br />
* teachers are enrolled in separate child course(s)<br />
<br />
==Problem areas we are working on ==<br />
<br />
===Student view===<br />
<br />
The "Student view" button has been removed completely.<br />
<br />
If there is time and a secure way can be found, it will be replaced by a menu to let the user assume a temporary role in the context of that course.<br />
<br />
===Teacher forum===<br />
<br />
Teacher forums were always a curious exception to normal forums, as they were not part of a course as such, and were not backed up.<br />
<br />
We're taking the opportunity to rectify this. The upgrade converts teacher forums with content to normal forums in section 0 of the course, and ensures that only teachers can access them. If the teacher forum had not been used in the course then it's not converted and will just dissappear.<br />
<br />
===Enrolment plugins===<br />
<br />
====Process of logging in====<br />
<br />
# load_user_capability() is called to load all the capabilities<br />
# check_enrolment_plugins() is called at the top of load_user_capability() to check all the enrolment plugins.<br />
# For each active plugin:<br />
##Check for setup_enrolments($user) and run it. This function will do all the processing needed to assign or unassign roles from the current user.<br />
# load_user_capability() continues and loads up all the roles<br />
# load_defaultuser_role() is called to add default site permissions (all users)<br />
<br />
====Process of checking access to a course====<br />
<br />
require_login($course->id) is called by the script and has logic like this:<br />
<br />
# Is the user a guest at site level?<br />
## Yes: Does the course allow guests?<br />
### Yes: return true (and further capabilities are checked by the script)<br />
### No: send the user to course/enrol.php for enrolment<br />
## No: continue below<br />
<br />
# Does the user have moodle/course:view in that (course) context?<br />
## Yes: then they can enter (and further capabilities are checked by the script)<br />
## No: is guest access allowed on the course?<br />
### Yes: assign temporary guest role to that user for that context (in session cache).<br />
### No: send the user to course/enrol.php for enrolment.<br />
<br />
====Process of enrolling====<br />
<br />
(more soon)<br />
<br />
==Scenario brainstorming==<br />
<br />
This section is for brainstorming some example roles that we would like to support. Note some of these *may* not be possible in 1.7.<br />
<br />
===Student===<br />
Obviously.<br />
<br />
===Site Designers===<br />
Is there a role for people involved in how the site looks but not full administrators? Thinking here of online control of themes rather than FTP theme uploading. But in either case they caneditlogos, caneditcss, candeditlevelatwhichthemeapplies.<br />
<br />
===Educational Authority Adviser===<br />
Someone who would want to browse the site and may be asked to comment or contribute to particular discussions or developments in school. Access for this role would be controlled by the school in the case of school level moodles but may be different if there were to be a Local Authority wide Moodle.<br />
<br />
===Educational Inspector===<br />
Someone who will visit the site to verify the school's self review that comments on home school relationships, extending the classroom etc. They may want to see summaries of usage and reports from surveys garnering parent and pupil views.<br />
<br />
===Second Marker / Moderator===<br />
A teacher within ths site that has access to assignments and quizzes from another teacher's course for second marking purposes. This may need additional functionality adding to the assignment module so that two sets of grades/feedback can be given to one set of assignments.<br />
<br />
===Peer observer of teaching===<br />
Many institutions encourage peer observation of teaching, to encourage reflection on practice. In online environments this will be similar to moderation or inspection. The peer observer would need to be able to experience the course "as a student", but also to be able to view summaries of usage, transcripts of interactions (forums/surveys/polls etc), grades assigned (e.g. in assignments).<br />
<br />
===External Examiner===<br />
Has all the rights of inspectors, but would also need to be able to review assignments and feedback, view forums, glossaries etc. However, would not want to post, feedback onto the site at all.<br />
<br />
===Parent===<br />
A parent will have one or more children in one or more institutions which could be using one or more moodle instances or a mixture of Learning Platforms. A parent's role will vary depending on the age of their children and whether they are contributing as a parent or a school supporter.<br />
<br />
In Early Years (EY=3+4 yr olds) and Key Stage 1 (KS1=5+6 yr olds) they may play/learn on an activity or write for the child. Parents often interpret homework tasks and read to their children perhaps filling in a joint reading diary. In Key Stage 2 (KS2=7-11 yr olds) parents would be more monitoring but may join in as well.<br />
<br />
In Key stages 3 (KS3=12-14 yr olds) and 4 (KS4=15+16 yr olds) this changes to more of a monitoring/awareness role where a parent would expect to have a summary report of attendance, attainment and general achievement on a weekly/monthly/termly or annual basis. Parents will often be asked to sign and write back comments about this review report.<br />
<br />
In all Key Stages there is a great need for parents to receive communication from the school which they can confirm they have received by signing a form. In some cases this may also involve making choices from a list. It may also involve payment for a trip or disco being returned so there could be the possibility of electronic payments. Also in all Key Satges there may be a home-school agreement which may be signed up to. Could this form part of a site policy system that incorporates a tickable list of activities the parent agrees to the child using (blogs/wikis/forums etc.)?<br />
<br />
Parent's evenings often involve complex booking systems that attempt to get parent's and teachers together. Easy for EY/KS1/KS2 very difficult for KS3/KS4. Wow would this help if it was built into the Learning Platform.<br />
<br />
In some cases there needs to be confidential communication between the parent and the teacher without the child being party to this. It may involve teaching and learning but could also involve a behaviour or medical issue. Often this may be done via a sealed letter or face to face. <br />
<br />
The latest incarnation of OfSTED with the Self Review Framework (SEF) there is a greater emphasis on schools gathering parent voice via surveys and discussion. There is a clear match here with parents have access to parental votes, questionnaires and discussions and for schools to be able to publish news, results and reports back to parents.<br />
<br />
In the UK the LP framework and agenda as being pushed by the DfES via Becta emphasises that within the mandatory groups and roles functionality the parent role is likely to be required to meet the LP Framework procurement standard.<br />
<br />
Again in the UK, parents have their own independent right of access to a child's educational records. Obviously, children's records must not be made available to other parties, including the parents of other children in the same class. Thus it would be necessary to associate parent accounts with their own child's accounts in such a way that they could, if so desired, have read access to their child's grades, answers and contributions, but generally not those of other children - this may be problematic in the case of wiki activities or forum posts.<br />
<br />
There is some concern that children's forum contributions etc may be constrained if their parents are able to read all that they write; this may be particularly problematic in areas such as Personal, Social and Health Education (PSHE), where some schools may choose to use obfuscated usernames.<br />
<br />
===Manager===<br />
''Please add text here...''<br />
<br />
===Weekly Seminar Leader===<br />
''In a university seminar, typically 8-15 students in their 3rd/4th year, each student is responsible for leading one topic in a study series. I ask each student to research 5-10 resources, then give a powerpoint presentation to the other students. This is followed by an in-class discussion and then online homework. The homework involves some fun quiz questions and then some reflective journal questions. I ask each seminar leader to prepare the quiz questions and journal questions as well as their presentation. To do that, I would like to assign activity-making/authoring roles to the student--either for a short period, or for duration of the whole course. Thus "Allow Quiz Authoring Role" or "Allow Assignment Authoring Role" at the course level or, if possible, even the Topic level (in a topic or week format course) would be important.''<br />
<br />
===Mentor/Mentee===<br />
''Please add text here...''<br />
<br />
===Community-Designed Rating Criteria===<br />
''The gradebook tends to be the domain of the teacher. What if community/peer ratings/marks could also be entered there? What if peer assessment criteria could be designed by the students, not just the teacher?''<br />
<br />
===Visitor===<br />
<br />
This would be a role whereby one could allow a visitor to visit one's classroom. This might be a colleague interested in seeing your course, or a journalist who might be writing an article about one's site. They should not be able to see the names of any students anywhere (eg recent activity, forum posts) for privacy reasons. They should be able to try out things like quizzes, and lessons but no grades would be recorded (like in teacher preview mode). They would not be able to participate in choices and forums but could view them. It would be read only in a way like former-student role below but without access to a particular student's records that former student role would grant.<br />
<br />
===Guest Speaker===<br />
<br />
This role would be similar to the Visitor role above, but would allow seeing student names, and also allow both reading and posting to a specific forum or forums. We often have "guest speakers" who read and respond to student forum posts. Right now we have to add them as students, which isn't ideal.<br />
<br />
===Former Student===<br />
This role would be of particular use for courses with rolling enrollments. This role would be one where a student had completed all of the requirements of a course (ie. assignments, quizzes etc.) but wished to have continued access to the course material for review or consultation. The key factor is that one would give access to the completed student to the notes he read, his work and the teacher's comments on it, but he would not be allowed to do anything that would take up the teacher's time. In other words, a sort-of read-only access to the course. How forums, which might contain pertinent information and would continue to grow, would be handled is a question. Perhaps the student would be shown only what was in the forums at the time he completed the course. He would not be allowed to see any new posts or add any himself. Same thing for database and glossary entries. In other words, a snapshot of the course at the time his regular enrollment ended. He shouldn't be able to see the names or profiles of any newly enrolled students for privacy reasons-hence the restrictions on forum access. One issue that would have to be dealt with would be changes to existing modules-such as resources. Does the student get access to the module as it was or as it is? We have no versioning of resources in Moodle so this would be a problem. What about a teacher changing a quiz question so that the answer is different? What would a former student see?<br />
<br />
===Alumnus=== <br />
An ALUMNUS should be able to search for all other ALUMNI of the school, interact with them and be enrolled in a separate course - which is like a META course with all the content of his learning and interaction - as well as capabilities to be a part of this ALUMNI only course. All the teachers of courses during school years should automatically be a part of the ALUMNI course .. which means when an ALUMNUS is enrolled in a course, the original teachers of all his courses get enrolled ? --[[User:Anil Sharma|Anil Sharma]] 20:54, 15 July 2006 (WST)<br />
<br />
===Librarian===<br />
<br />
Reference Librarians have an active role in most of the courses taught at some schools such as Earlham College (with Bibliographic Instruction). The Librarian role within Moodle could encompass default read access to all courses (unless prohibited by course teacher) and read access to all components of the course unless access is barred (again by teacher). The Librarians would also perhaps have a block called perhaps Reference Services or Reference Desk with write access where they could deposit resources. Also this block might have a chat applet whereby enrolled students could chat to the Reference Librarian on duty about their bibliographic research needs.<br />
<br />
In schools there is often a book review system. This may be covered by the lending system database but may not in which case a librarian may neeed to have a course area they can create a database template to handle the reviews in which case they may have a normal teacher style role? Off topic but course an integration with common schools database systems would be great.<br />
<br />
===Teacher===<br />
<br />
Teachers should have read access to other Teacher's courses unless explictly prohibited. They should be able to set parts of their own course to be totally private (perhaps even to admin?). Just as each activity can currently be set to have group access, each activity could have a permissions field. Teachers could set default permissions for all activities on their course (eg they might disallow Librarian access for example) and then change the access permission for an individual activity. <br />
<br />
I think that what is needed is a simple heirarchy of permissions and levels of granularity.<br />
<br />
I would take issue with "teachers should have read access to other teacher's courses unless explicitly prohibited." This is a violation of the students' privacy as how they perform and what they do in one class isn't the business of another teacher. Moreover, in the real world a teacher wouldn't suddenly go sit in on a colleague's class without asking permission first. I would not have appreciated such an invasion of privacy as either a teacher or a student. It could be an option, but shouldn't be default.--[[User:N Hansen|N Hansen]] 19:54, 12 June 2006 (WST)<br />
<br />
===Community Education Tutors/Trainers===<br />
Teachers may be community adult education trainers making use of a school moodle so must only have access to their courses unless given access elsewhere. They would not necessarily get the default teacher privileges.<br />
<br />
===Secretary/Student Worker===<br />
<br />
We often have faculty who want their departmental secretary or student worker to scan and upload files and perhaps create resources. Currently they have to be given teacher access to the course. This is dangerous from a FERPA standpoint since they could easily get access to grades.<br />
<br />
===Teaching Assistant===<br />
<br />
Our Faculty frequently have undergraduate students acting as Teaching Assistants. These students need to be able to add resources, create assignments, and possibly grade assignments. However, due to FERPA they cannot have access to other students' overall grade information. I think the requirements here are slightly different than those of Secretary/Student Worker<br />
<br />
===Student - FERPA rights===<br />
<br />
A student that has asserted their FERPA rights to non-disclosure. Typically includes not publishing their name<br />
in any public place. Could include this student only being seen with an "alias" within course spaces. Is this an attribute rather<br />
than a role?<br />
<br />
===Help Desk===<br />
<br />
Help desk agents that have read access for the purposes of trouble shooting. Some care in placing this role within a hierarchy<br />
of inheritance is needed, full access will be problematic with FERPA.<br />
<br />
===Admin - Catgory based===<br />
<br />
Basically a person in between full Admin and Creator that has the permissions of an Admin but only with respect to courses and students. Currently a Creator has permissions site-wide which does not always meet the requirements of a given organisation (e.g. Department A may not be happy that a person from Department B can create/modify courses within Department A's area). The ability to designate a Creator within a specific category would allow areas to be set up for a faculty/department/organisation and allow the Admin for that area to create/delete courses, upload users, add site-wide entries to the calendar etc.<br />
<br />
===Process Roles===<br />
<br />
organising the learning process for a group you wish to have the choice to place students in differnt roles: examples of this are:<br />
* Give a student the role of forum-moderator with edit and chunk-rights<br />
* Give students different roles & rights in a Webquest design (and change these roles next week<br />
* Give students different resources, depending of their roles in a rolegame/simulation<br />
* Give a student the rights to create the section content of next week (and only that week..)<br />
<br />
==Things to finish for 1.7 Beta==<br />
'''18 Sept 2006'''<br />
<br />
#Remove core references to user_student, user_teacher, user_admin, user_coursecreator tables. [Yu]<br />
#Address function: isteacher, isadmin, isstudent [Yu]<br />
#Remove "view" capabilities from all modules unless required [Vy]<br />
#Remove all old references from remaining Blocks [Vy]<br />
#Metacourses [Skodak]<br />
#Add risks to GUI[Skodak]<br />
#Enrolment plugins [Martin and Alastair]<br />
#[[Development:Stats_roles_1.7|Statistics]] [Penny]<br />
#Fix Loginas<br />
#Add category-level assigns [Yu]<br />
#[[Development:Backup_roles_1.7|Backups]] [Eloy?]<br />
<br />
===Proposal for interface enhancement===<br />
Martin asked some questions, here are my answers. The sketches below are not worked out proposals. Their task is to visualize the idea. The exact colours and functionality may be defined after possible agreement about the proposals. The Green, orange and red columns support the meaning of the options from "allow" to "prohibit" (If you may want to see larger images please click onto the image or the "Enlarge" icon below the image.)<br />
<br />
The list of possible settings is very long and '' "... the problem is not to overwhelm people with information" ''. <br />
<br />
[[Image:01_moodle_define_roles_structured.png|thumb=01_moodle_define_roles_structured_pre.png]]<br />
<br />
1) One proposal is to use colour to structure the sections and the columns. Picture 1 shows that the user can keep a much better overview when the list is divided into meaningful different coloured columns and clear sections.<br />
<br style="clear:both;" /><br />
<br />
[[Image:02_moodle_define_roles_collapsed.png|thumb=02_moodle_define_roles_collapsed_pre.png]]<br />
<br />
2) A second proposal is to reduce the amount of information the user is shown at the same time. The YUI interface library offers great support to show/hide sections of the page by clicking on specific elements. <br />
<br />
For example click on an icon beside the sub heading "Course categories" and show/hide all table rows with the CLASS "course-category".<br />
<br style="clear:both;" /><br />
<br />
[[Image:03_moodle_define_roles_tooltip.png|thumb=03_moodle_define_roles_tooltip_pre.png]]<br />
<br />
3) '' "The main problem is the last column for risk ... we were thinking of putting little icons in there ..." ''<br />
Icons are good when they tell the user more about possible actions/meanings then the letters. I am not sure if this is the case here. For both - icons or letters - the YUI tool-tip function would be able to give the user valuable information about the meaning.<br />
<br style="clear:both;" /><br />
<br />
==See also==<br />
<br />
*[[Development:Hardening new Roles system]]<br />
*[[Development:Roles and modules]]<br />
*Using Moodle course:<br />
**[http://moodle.org/mod/forum/view.php?f=941 Roles and Capabilities forum]<br />
**Key discussions at Using Moodle forums:<br />
***[http://moodle.org/mod/forum/discuss.php?d=38788 Roles and Permissions architecture]<br />
***[http://moodle.org/mod/forum/discuss.php?d=56302#256313 An example of admin roles as set in the database]<br />
<br />
[[Category:Developer|Roles]]<br />
[[Category:Roles]]<br />
<br />
[[fr:Developpement:Roles]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Upload_users&diff=25798Upload users2007-08-09T13:26:10Z<p>Delius: /* Flat file format */ the bug about not enrolling user into course if user already exists has been fixed</p>
<hr />
<div>Location: ''Administration > Users > Accounts > Upload users''<br />
<br />
<br />
==Flat file format==<br />
<br />
Users may be imported, enrolled on courses and organised into groups via flat file.<br />
<br />
Firstly, note that '''it is usually not necessary to import users in bulk''' - to keep your own maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as connecting to existing external databases or letting the users create their own accounts. See the Authentication section in the admin menus.<br />
<br />
If you are sure you want to import multiple user accounts from a text file, then you need to format your text file as follows:<br />
<br />
* Each line of the file contains one record<br />
* Each record is a series of data separated by commas<br />
* The first record of the file is special, and contains a list of fieldnames. This defines the format of the rest of the file.<br />
<br />
:'''Required fieldnames''': these fields must be included in the first record, and defined for each user<br />
:<p><code>username, password, firstname, lastname, email</code></p><br />
<br />
:'''Default fieldnames''': these are optional - if they are not included then the values are taken from the primary admin<br />
:<p><code>institution, department, city, country, lang, auth, timezone</code></p><br />
<br />
:'''Optional fieldnames''': all of these are completely optional. The course names are the "shortnames" of the courses - if present then the user will be enrolled as students in those courses. Group names must be associated to the corresponding courses, i.e. group1 to course1, etc.<br />
:<p><code>idnumber, icq, phone1, phone2, address, url, description, mailformat, maildisplay, htmleditor, autosubscribe, course1, course2, course3, course4, course5, group1, group2, group3, group4, group5, type1, type2, type3, type4, type5</code></p><br />
<br />
* Commas within the data should be encoded as &#44 - the script will automatically decode these back to commas.<br />
* For Boolean fields, use 0 for false and 1 for true.<br />
* Types are used to tell Moodle whether the user is a student or a teacher if a corresponding course exists (e.g. type2 corresponds to course2). 1 = Student, 2 = Editing Teacher, and 3 = Non-editing Teacher. If type is left blank, or if no course is specified, the user is default to student.<br />
* For courses, use the short name for the course<br />
* Note: If a user is already registered in the Moodle user database, this script will return the userid number (database index) for that user, and will enrol the user as a student in any of the specified courses WITHOUT updating the other specified data.<br />
<br />
Here is an example of a valid import file:<br />
<br />
<code>username, password, firstname, lastname, email, lang, idnumber, maildisplay, course1, group1, type1<br /><br />
jonest, verysecret, Tom, Jones, jonest@someplace.edu, en, 3663737, 1, Intro101, Section 1, 1<br /><br />
reznort, somesecret, Trent, Reznor, reznort@someplace.edu, en_us, 6736733, 0, Advanced202, Section 3, 3</code><br />
<br />
(Text copied from [http://moodle.org/help.php?file=uploadusers.html Upload users help file].)<br />
<br />
==Updating existing accounts==<br />
<br />
By default Moodle assumes that you will be creating new user accounts, and skips records where the username matches an existing account. However, if you set "Update existing accounts" to '''Yes''', the existing user account will be updated.<br />
<br />
When updating existing accounts you can change usernames as well. Set "Allow renames" to '''Yes''' and include in your file a field called <code>oldusername</code>.<br />
<br />
'''Warning''': any errors updating existing accounts can affect your users badly. Be careful when using the options to update.<br />
<br />
==Character encoding==<br />
The file must have the same encoding as your language pack. In Moodle 1.7 and later versions it is always UTF-8. <br />
<br />
==Hints==<br />
<br />
If you use a spreadsheet program such as Excel to create your .csv file, check the resulting output in a text editor before you upload it. It is possible to get trailing commas on each line from an empty field if you have added and deleted columns of information prior to saving the final file. Also check the character encoding.<br />
<br />
==See also==<br />
<br />
*[[Flat file]]<br />
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?] forum discussion<br />
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=58215 Making Email Optional] forum discussion<br />
<br />
[[Category:Authentication]]<br />
[[Category:Enrolment]]<br />
<br />
[[fr:Importer des utilisateurs]]<br />
[[ja:ユーザのアップロード]]<br />
[[zh:上传用户]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Roles_FAQ&diff=21981Roles FAQ2007-03-30T18:51:03Z<p>Delius: /* How can I prevent course creators being listed as course participants? */ This section is no longer needes since the fix for MDL-8093</p>
<hr />
<div>{{Roles}}<br />
<br />
==What is the definition of a...==<br />
<br />
;Role<br />
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator<br />
;Capability<br />
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]<br />
;Permission<br />
:A setting for a capability<br />
;Context<br />
:A "space" in Moodle, such as courses, activity modules or blocks<br />
<br />
==Why isn't my role change taking effect?==<br />
<br />
Role changes only take effect after the next login from that user. Regarding testing new roles, please refer to the information in [[Manage roles]].<br />
<br />
==Why are participants being added automatically when a new course is created?==<br />
<br />
If a user is assigned a role in the site/system or course category context then the user has this role in ALL courses in that context. Thus users who are students or teachers at the category level appear as course participants in all courses in that category.<br />
<br />
Please check ''Administration > Users > Permissions > Assign roles'' and also the Assign roles link in course categories page and unassign users as necessary.<br />
<br />
==Why are there differences in the users listed as course participants and users assigned roles in a course?==<br />
<br />
Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation. <br />
<br />
<br />
<br />
==How can I prevent administrators being listed as course participants?==<br />
<br />
Ensure that administrators are not assigned another role in addition to their admin role.<br />
<br />
==Why are hidden assignments still visible?==<br />
<br />
Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].<br />
<br />
==What is a hierarchy of permissions?==<br />
<br />
This determines which permission wins or is going to be in effect if there is an apparent conflict. For example, the site allows all students the permission to to post in forums, but a teacher might prevent that right in a particular course. The hierarchy of permissions would allow a student to post in one course but not in another course.<br />
<br />
==Are there any differences in Roles in Moodle 1.7 and 1.8?==<br />
{{Moodle 1.8}}<br />
In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''site'' context.<br />
<br />
The site context in Moodle 1.8 is the "front page course" and its activities. Roles may be assigned in the site context via ''Administration > Front Page > Front Page roles''.<br />
<br />
[[Category:Roles]]<br />
[[Category:FAQ]]<br />
<br />
[[es:FAQ_roles]]<br />
[[fr:FAQ des rôles]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Roles_FAQ&diff=21980Roles FAQ2007-03-30T18:49:08Z<p>Delius: /* Why are participants being added automatically when a new course is created? */</p>
<hr />
<div>{{Roles}}<br />
<br />
==What is the definition of a...==<br />
<br />
;Role<br />
:An identifier of the user's status in some context, for example Teacher, Student and Forum moderator<br />
;Capability<br />
:A description of a particular Moodle feature, for example [[Capabilities/moodle/blog:create|moodle/blog:create]]<br />
;Permission<br />
:A setting for a capability<br />
;Context<br />
:A "space" in Moodle, such as courses, activity modules or blocks<br />
<br />
==Why isn't my role change taking effect?==<br />
<br />
Role changes only take effect after the next login from that user. Regarding testing new roles, please refer to the information in [[Manage roles]].<br />
<br />
==Why are participants being added automatically when a new course is created?==<br />
<br />
If a user is assigned a role in the site/system or course category context then the user has this role in ALL courses in that context. Thus users who are students or teachers at the category level appear as course participants in all courses in that category.<br />
<br />
Please check ''Administration > Users > Permissions > Assign roles'' and also the Assign roles link in course categories page and unassign users as necessary.<br />
<br />
==Why are there differences in the users listed as course participants and users assigned roles in a course?==<br />
<br />
Users assigned roles in a higher context, for example users assigned the role of teacher in a course category context, may appear as course participants. The discussion [http://moodle.org/mod/forum/discuss.php?d=59900 Discrepancies between Assign Roles lists and Participants list] contains a longer explanation. <br />
<br />
==How can I prevent course creators being listed as course participants?==<br />
<br />
Either:<br />
*In ''Administration > Users > Permissions > [[Assign roles]]'', unassign course creators then use the Hidden assignments check box to re-assigned them hidden<br />
Or:<br />
*In ''Administration > Users > Permissions > Define roles'', edit the course creator role and change the permissions for [[Capabilities/moodle/course:view|moodle/course:view]] and [[Capabilities/moodle/course:update|moodle/course:update]] from Allow to Inherit<br />
<br />
A further possibility is to assign course creators in the course category context via the assign roles link at the top right of a course category page.<br />
<br />
==How can I prevent administrators being listed as course participants?==<br />
<br />
Ensure that administrators are not assigned another role in addition to their admin role.<br />
<br />
==Why are hidden assignments still visible?==<br />
<br />
Hidden assignments are not hidden from admins or teachers i.e. users with the [[Capabilities/moodle/role:viewhiddenassigns|viewhiddenassigns capability]].<br />
<br />
==What is a hierarchy of permissions?==<br />
<br />
This determines which permission wins or is going to be in effect if there is an apparent conflict. For example, the site allows all students the permission to to post in forums, but a teacher might prevent that right in a particular course. The hierarchy of permissions would allow a student to post in one course but not in another course.<br />
<br />
==Are there any differences in Roles in Moodle 1.7 and 1.8?==<br />
{{Moodle 1.8}}<br />
In addition to many Roles fixes and refinements (see the list of [http://tracker.moodle.org/secure/IssueNavigator.jspa?mode=hide&requestId=10221 Roles improvements] in the Tracker), in Moodle 1.8 the ''system'' context is separated from the ''site'' context.<br />
<br />
The site context in Moodle 1.8 is the "front page course" and its activities. Roles may be assigned in the site context via ''Administration > Front Page > Front Page roles''.<br />
<br />
[[Category:Roles]]<br />
[[Category:FAQ]]<br />
<br />
[[es:FAQ_roles]]<br />
[[fr:FAQ des rôles]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Maintenance_mode&diff=21943Maintenance mode2007-03-30T08:51:02Z<p>Delius: </p>
<hr />
<div>The idea of maintenance mode is to prevent any users other than admin to use the site while the maintenance process takes place.<br />
<br />
When students/guests/teachers try access a course in maintenance mode, they will obtain a message saying the course is in maintenance mode. A customized message may be added, perhaps stating when the site will be available again or giving the reason for doing maintenance.<br />
<br />
If for some reason the webinterface is not available you can also put the Moodle installation in maintenance mode by creating a file called ''maintenance.html'' in the folder called ''1'' in your moodle data folder. Any text in that file will be displayed to users trying to access anything other than the frontpage.<br />
<br />
==See also==<br />
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=46451 Maintenance mode?] forum discussion<br />
<br />
[[Category:Administrator]]<br />
<br />
[[fr:Mode de maintenance]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Calendar&diff=20674Calendar2007-02-20T16:07:02Z<p>Delius: /* See also */ added link to calendar discussion forum</p>
<hr />
<div>{{Calendar}}<br />
<br />
The Calendar displays the following events:<br />
<br />
* Site (event viewable in all courses - created by admin users)<br />
* Course (event viewable only to course members - created by teachers)<br />
* Groups (event viewable only by members of a group - created by teachers)<br />
* User (personal event a student user can create - viewable only by the user)<br />
<br />
Events are added to the calendar, and can be aimed at individual users, your defined groups, or your courses. Adding closing dates to assignments, forums, quizzes, etc. will cause them to show up in the [[Calendar block|calendar block]]. You can view previous or future months on Calendar by clicking the left/right arrows next to the current month's name. The current date is outlined. You can hide or show various categories of events by clicking on the color key below the calendar. This can make the calendar easier to read (especially if there are many events on the calendar). For example, if you wanted to hide Group event dates (events assigned to learner Groups you create), click "Group events" on the bottom of the Calendar. This would hide all group events, and the color code would disappear from the link on the calendar. To show the events again, click the Group Events link again.<br />
<br />
Both the daily detail screen and the monthly detail screen have the Preferences button in the upper right. This button leads to a screen like this: The last two settings ('Maximum upcoming events' and 'Upcoming events look-ahead') affect how the Upcoming Events block displays information. You may change any of these settings to suit your class needs. When you have finished any changes, click Save changes. <br />
<br />
Both the daily and monthly detail screens have the New Event button. This allows you to manually add events for your classes (remember that the system will automatically add due dates for assignments, quizzes, etc. when you create those activities). <br />
<br />
==See also==<br />
<br />
*[[Calendar (administrator)]]<br />
*[http://moodle.org/mod/forum/view.php?f=345 Calendar discussion forum]<br />
<br />
[[Category:Teacher]]<br />
[[Category:Calendar]]<br />
<br />
[[fr:Calendrier]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Installing_AMP&diff=19558Installing AMP2007-01-24T18:09:18Z<p>Delius: /* Windows */ the url of the download page has changed</p>
<hr />
<div>AMP or AMPPlite stands for '''A'''pache, '''M'''ySQL & '''P'''HP. Moodle is written in a scripting language called [[PHP]] and stores most of its data in a database. The recommended database is [[MySQL]]. Before installing Moodle you must have a working PHP installation and a working database to turn your computer into a functional web server platform. XAMP is a Windows and MAMP is a Mac OS version. <br />
Moodle does have [[Complete install packages]] in the [http://download.moodle.org/ download section] as well as the Moodle only package.<br />
<br />
The AMP individual applications can be tricky to set up for average computer users. This page has been written to try to make this process as simple as possible for different platforms. <br />
<br />
<br />
== Hosting Service ==<br />
<br />
Unfortunately hosting services vary quite a lot in the way they work. Some will even install Moodle for you.<br />
<br />
Most will offer a web-based control panel to control your site, create databases and set up cron. Some may also offer terminal access via ssh, so that you can use the command shell to do things.<br />
<br />
You should work your way through the [[Installing Moodle|Installation guide]] and take each step at a time. Ask your hosting provider if you get stuck.<br />
<br />
<br />
== Mac OS X ==<br />
<br />
The easiest way to do this is use the [[Apache]] server that Apple provides, and add PHP and MySQL using Marc Liyanage's packages. Both of the pages below come with good instructions that we won't duplicate here:<br />
<br />
* '''PHP''': Download from here: http://www.entropy.ch/software/macosx/php/<br />
* '''MySQL''': Download here: http://www.entropy.ch/software/macosx/mysql/<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
Go here for a [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client]] (not server) Mac.<br />
<br />
== Red Hat Linux ==<br />
<br />
You should install all available RPM packages for Apache, PHP and MySQL. One package that people frequently forget is the php-mysql package which is necessary for PHP to talk to MySQL.<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
A more detailed walkthrough is here: [[RedHat Linux installation]]<br />
<br />
== Windows ==<br />
<br />
Installing Moodle '''for the first time''' on a [[Localhost]] (a stand alone computer) is easy and can be a very useful tool even if a web based production Moodle Server is available for use. These instructions work on a Window XP computer.<br />
#On the [http://download.moodle.org/windows/ Windows packages] download page, choose the version you would like. Click on the download link in the rightmost column. This will download a large zip file.<br />
#Unzip the downloaded file at c: and keep the path structure for all the files. <br />
#Rename the just created c:\moodle to c:\xampplite (c:\xampplite will be our example) but you could rename it c:\moodle16 or c:\moodle17 or C:\testMoodle or whatever .<br />
#Using Windows Explorer run the file c:\xampplite\set_xampp.bat which will make sure all the configuration files use c:\xampplite as the home or root directory.<br />
#The following steps assume that the web server will be able to use port 80 on your computer. See [[Windows_installation_using_XAMPP#Skype |troubleshooting if you are running Skype]] which also likes to use this port as a default. <br />
#There many ways to start the localhost webserver from this point for the Moodle install. Here are two ways.<br />
##Slightly faster<br />
###Using Windows Explorer run the file c:\xampplite\restart_xampp.bat and do not close the window that opens.<br />
##Still fast<br />
###In Windows Explorer click on c:\xampplite\apache_start to start the Apache web server. This opens a new window that you should leave open.<br />
###In Windows Explorer click on c:\xampplite\mysql_start to start the MySQL database server. This opens yet another new window that you should leave open.<br />
#In your favorite Web browser, go to address bar and type "localhost" and press enter or go.<br />
#This will start the Moodle Install process, which the [[Installing Moodle]] [[Installing_Moodle#Go_to_the_admin_page_to_continue_configuration| MoodleDoc page section]] describes in a little bit more detail. This can take some time for a new user. '''Don't panic''', you can change things later and the install process will tell you what you absolutely have to fill in or correct.<br />
<br />
===Easier Moodle restarts===<br />
There are lots of ways to start a Moodle after an install. Most Moodlers will have one or more "localhost" links on their computer installed in "Favorites" or even as a browser's default opening screen. But first a web server has to be started. Here are two ways to start them. <br />
====Automatic Window services startup====<br />
In order to make starting Moodle more convenient in the future you could install the web and database servers as Windows services that are started automatically. To do this go to Start -> Run... and type the command "c:/xampplite/service.exe -install" into Open box. Then click OK.<br />
<br />
Start Moodle by typing localhost in the web browser and/or adding localhost as a favorite site.<br />
====Single button service startups====<br />
Sometimes there are more than one localhost installed on a computer. Create a short cut on the start menu, favorites or desktop that points to each specific file like c:\xampplite\restart_xampp.bat . Lable each shortcut to a localhost differently, for example C_MoodleXampp, or Moodle16 or Moodle17 or whatever. <br />
<br />
Start the Moodle by placing localhost in the web browser or adding it as a favorite site. Which ever localhost you restarted, that is the Moodle your web browser will find.<br />
<br />
==Other install options==<br />
Instead of using this package you can also install XAMPP and Moodle separately as explained on the page [[Windows_installation_using_XAMPP]]. <br />
<br />
As an alternative to the above package you could use a package like EasyPHP that bundles all the software you need into a single Windows application. Note that the EasyPHP 1.8 uses older versions of the software that are too old for Moodle 1.6. Also many menus for EasyPHP are still in French. EasyPHP may be a good option again once its version 2.0 is released.<br />
<br />
Here you can find steps for an [[IIS]]: [[Windows installation]] for XAMPP or Windows 2003 .<br />
<br />
==Testing PHP==<br />
Once you have installed your web server and PHP you should be able to create a file (for example phpinfo.php in the document root) with the following in it:<br />
<br />
<?php phpinfo()?><br />
<br />
You should be able to open this file in a web browser by going to to the URL '''localhost/phpinfo''' and see a web page that has PHP status information in it such as [[phpinfo|this]].<br />
<br />
==See also==<br />
<br />
*[[Installing Moodle]]<br />
*[[Installation FAQ]]<br />
*[[Upgrading Moodle]]<br />
*[[Debian GNU/Linux installation]]<br />
*[[Complete install packages]], also includes instructions for creating a stand alone (localhost) installation on a single computer.<br />
<br />
[[Category:Core]]<br />
[[Category:Administrator]]<br />
[[Category:Installation]]<br />
<br />
[[es:Instalación AMP]]<br />
[[ja:AMPのインストール]]<br />
[[ru:Установка AMP]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Installing_AMP&diff=19374Installing AMP2007-01-19T14:33:52Z<p>Delius: /* Testing PHP */ We use long php tag</p>
<hr />
<div>AMP or AMPPlite stands for '''A'''pache, '''M'''ySQL & '''P'''HP. Moodle is written in a scripting language called [[PHP]] and stores most of its data in a database. The recommended database is [[MySQL]]. Before installing Moodle you must have a working PHP installation and a working database to turn your computer into a functional web server platform. XAMP is a Windows and MAMP is a Mac OS version. <br />
Moodle does have [[Complete install packages]] in the [http://download.moodle.org/ download section] as well as the Moodle only package.<br />
<br />
The AMP individual applications can be tricky to set up for average computer users. This page has been written to try to make this process as simple as possible for different platforms. <br />
<br />
<br />
== Hosting Service ==<br />
<br />
Unfortunately hosting services vary quite a lot in the way they work. Some will even install Moodle for you.<br />
<br />
Most will offer a web-based control panel to control your site, create databases and set up cron. Some may also offer terminal access via ssh, so that you can use the command shell to do things.<br />
<br />
You should work your way through the [[Installing Moodle|Installation guide]] and take each step at a time. Ask your hosting provider if you get stuck.<br />
<br />
<br />
== Mac OS X ==<br />
<br />
The easiest way to do this is use the [[Apache]] server that Apple provides, and add PHP and MySQL using Marc Liyanage's packages. Both of the pages below come with good instructions that we won't duplicate here:<br />
<br />
* '''PHP''': Download from here: http://www.entropy.ch/software/macosx/php/<br />
* '''MySQL''': Download here: http://www.entropy.ch/software/macosx/mysql/<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
Go here for a [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client]] (not server) Mac.<br />
<br />
== Red Hat Linux ==<br />
<br />
You should install all available RPM packages for Apache, PHP and MySQL. One package that people frequently forget is the php-mysql package which is necessary for PHP to talk to MySQL.<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
A more detailed walkthrough is here: [[RedHat Linux installation]]<br />
<br />
== Windows ==<br />
<br />
Installing Moodle '''for the first time''' on a [[Localhost]] (a stand alone computer) is easy and can be a very useful tool even if a web based production Moodle Server is available for use. These instructions work on a Window XP computer.<br />
#In the [http://download.moodle.org/?lang=en Download section], find the second group called "Complete Install Packages (Moodle+Apache+MySQL+PHP)" and choose the version you would like. Click on the download link on the far right, which will download a large zip file.<br />
#Unzip the downloaded file at c: and keep the path structure for all the files. <br />
#Rename the just created c:\moodle to c:\xampplite (c:\xampplite will be our example) but you could rename it c:\moodle16 or c:\moodle17 or C:\testMoodle or whatever .<br />
#Using Windows Explorer run the file c:\xampplite\set_xampp.bat which will make sure all the configuration files use c:\xampplite as the home or root directory.<br />
#The following steps assume that the web server will be able to use port 80 on your computer. See [[Windows_installation_using_XAMPP#Skype |troubleshooting if you are running Skype]] which also likes to use this port as a default. <br />
#There many ways to start the localhost webserver from this point for the Moodle install. Here are two ways.<br />
##Slightly faster<br />
###Using Windows Explorer run the file c:\xampplite\restart_xampp.bat and do not close the window that opens.<br />
##Still fast<br />
###In Windows Explorer click on c:\xampplite\apache_start to start the Apache web server. This opens a new window that you should leave open.<br />
###In Windows Explorer click on c:\xampplite\mysql_start to start the MySQL database server. This opens yet another new window that you should leave open.<br />
#In your favorite Web browser, go to address bar and type "localhost" and press enter or go.<br />
#This will start the Moodle Install process, which the [[Installing Moodle]] [[Installing_Moodle#Go_to_the_admin_page_to_continue_configuration| MoodleDoc page section]] describes in a little bit more detail. This can take some time for a new user. '''Don't panic''', you can change things later and the install process will tell you what you absolutely have to fill in or correct.<br />
<br />
===Easier Moodle restarts===<br />
There are lots of ways to start a Moodle after an install. Most Moodlers will have one or more "localhost" links on their computer installed in "Favorites" or even as a browser's default opening screen. But first a web server has to be started. Here are two ways to start them. <br />
====Automatic Window services startup====<br />
In order to make starting Moodle more convenient in the future you could install the web and database servers as Windows services that are started automatically. To do this go to Start -> Run... and type the command "c:/xampplite/service.exe -install" into Open box. Then click OK.<br />
<br />
Start Moodle by typing localhost in the web browser and/or adding localhost as a favorite site.<br />
====Single button service startups====<br />
Sometimes there are more than one localhost installed on a computer. Create a short cut on the start menu, favorites or desktop that points to each specific file like c:\xampplite\restart_xampp.bat . Lable each shortcut to a localhost differently, for example C_MoodleXampp, or Moodle16 or Moodle17 or whatever. <br />
<br />
Start the Moodle by placing localhost in the web browser or adding it as a favorite site. Which ever localhost you restarted, that is the Moodle your web browser will find.<br />
<br />
==Other install options==<br />
Instead of using this package you can also install XAMPP and Moodle separately as explained on the page [[Windows_installation_using_XAMPP]]. <br />
<br />
As an alternative to the above package you could use a package like EasyPHP that bundles all the software you need into a single Windows application. Note that the EasyPHP 1.8 uses older versions of the software that are too old for Moodle 1.6. Also many menus for EasyPHP are still in French. EasyPHP may be a good option again once its version 2.0 is released.<br />
<br />
Here you can find steps for an [[IIS]]: [[Windows installation]] for XAMPP or Windows 2003 .<br />
<br />
==Testing PHP==<br />
Once you have installed your web server and PHP you should be able to create a file (for example phpinfo.php in the document root) with the following in it:<br />
<br />
<?php phpinfo()?><br />
<br />
You should be able to open this file in a web browser by going to to the URL '''localhost/phpinfo''' and see a web page that has PHP status information in it such as [[phpinfo|this]].<br />
<br />
==See also==<br />
<br />
*[[Installing Moodle]]<br />
*[[Installation FAQ]]<br />
*[[Upgrading Moodle]]<br />
*[[Debian GNU/Linux installation]]<br />
*[[Complete install packages]], also includes instructions for creating a stand alone (localhost) installation on a single computer.<br />
<br />
[[Category:Core]]<br />
[[Category:Administrator]]<br />
[[Category:Installation]]<br />
<br />
[[es:Instalación AMP]]<br />
[[ja:AMPのインストール]]<br />
[[ru:Установка AMP]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Developer_documentation&diff=19165Development:Developer documentation2007-01-07T11:25:30Z<p>Delius: Undoing last edits which changed text to Russian</p>
<hr />
<div><p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>.<br /><br />If you are a developer, you probably want to change your [[Special:Preferences|preferences]] to include the Development namespace in searches.</p><br />
<br />
==Guidelines==<br />
The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:<br />
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers<br />
*[[Moodle architecture]] spells out the basic design goals behind Moodle<br />
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface<br />
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS<br />
*[[Unit tests]] explains how to run the unit tests, and how to write new test cases.<br />
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc<br />
*[[Development:Working with the Community|Working with the Community]] explains how to engage with the dev community and discuss changes<br />
<br />
== Resources and tools ==<br />
<br />
*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle<br />
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues<br />
*[http://moodle.org/mod/forum/view.php?id=55 General developer forum]<br />
*[http://moodle.cvs.sourceforge.net/moodle/moodle/ CVS code] - browse the Moodle code via the web<br />
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code<br />
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - automatically generated documentation<br />
*[[Development:Database Schema|Database Schema]] - for recent releases<br />
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course<br />
*[http://developer.yahoo.com/yui YUI documentation] - YUI is the official AJAX library in moodle.<br />
*[[Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.<br />
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD<br />
<br />
==How you can contribute==<br />
<br />
The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional functionality. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. The following types of plugins currently exist (in alphabetical order):<br />
*[[Modules (developer)|Activity modules]]<br />
*[[Development:Admin reports|Admin reports]]<br />
*[[Assignment types]]<br />
*[[Authentication|Authentication methods]]<br />
*[[Blocks Howto|Blocks]]<br />
*[[Course formats]]<br />
*[[Database fields (developer)|Database fields]]<br />
*[[Database presets]]<br />
*[[Enrolment plugins (developer)|Enrolment plugins]]<br />
*[[Development:Filters|Filters]]<br />
*[[Question_engine]]<br />
*[[Question import/export formats]]<br />
*[[Question bank|Question bank teacher docs]]<br />
*[[Question_engine#Question_types|Question types developper docs]]<br />
*[[Quiz reports]]<br />
*[[Resource types]]<br />
*[[SSO plugins]]<br />
<br />
There are also ways you can contribute that don't involve PHP programming:<br />
*[[Themes]]<br />
*[[Translation]]<br />
*[[Database Schemas|Database schemas]]<br />
<br />
You can also help a lot by<br />
*[[Tests|Testing]]<br />
*[[Tracker|Participating in the bug tracker]]<br />
<br />
==Plans for the future==<br />
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.<br />
<br />
Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.<br />
*[[Roadmap]]<br />
*[[Developer notes]]<br />
*[[Student projects]]<br />
*[[Developer conference|Developer conferences]]<br />
<br />
==Documentation for core components==<br />
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].<br />
<br />
*[[Development:Migration to Role-driven model|Migration to Role-driven model]] @ v[[1.7]]<br />
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]<br />
*[[Question engine]]<br />
*[[Quiz developer docs|Quiz module]]<br />
*[[SCORM schema|SCORM module 1.5 schema]]<br />
*[[Authentication API]]<br />
*[[Stats package]]<br />
*[[Email processing]]<br />
*[[Cookieless Sessions]]<br />
*[[Development:lib/formslib.php|Formslib]] for quickly writing code to display and process more accessible and secure forms.<br />
<br />
==Documentation for contributed code==<br />
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib area] of the Moodle [[CVS]] repository. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. Developer documentation for these components should be listed here.<br />
<br />
==See also==<br />
*[http://security.moodle.org/ Moodle Security Centre]<br />
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services<br />
<br />
[[Category:Developer]]<br />
[[es:Documentación para Desarrolladores]]<br />
[[fr:Documentation développeur]]<br />
[[zh:开发者文档]]<br />
[[ja:開発者ドキュメント]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development_talk:Open_protocol_for_accessing_question_engines&diff=18264Development talk:Open protocol for accessing question engines2006-11-29T15:17:50Z<p>Delius: My support</p>
<hr />
<div>I very much support Tim's work on this. I will be watching this page and whenever our experience from designing and then simplifying RQP might be helpful I will mention it. --[[User:Gustav Delius|Gustav Delius]] 09:17, 29 November 2006 (CST)</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Pedagogy&diff=18261Pedagogy2006-11-29T15:13:13Z<p>Delius: /* Where Moodle can do better and what we're doing about it */ typos</p>
<hr />
<div>Let's sit back and really reflect on the pedagogy that is at the core of what we, as online educators, are trying to do.<br />
<br />
==Moodle in three short paragraphs==<br />
<br />
The heart of Moodle is courses that contain activities and resources. There are about 20 different types of activities available (forums, glossaries, wikis, assignments, quizzes, choices (polls), scorm players, databases etc) and each can be customised quite a lot. The main power of this activity-based model comes in combining the activities into sequences and groups, which can help you guide participants through learning paths. Thus, each activity can build on the outcomes of previous ones.<br />
<br />
There are a number of other tools that make it easier to build communities of learners, including blogs, messaging, participant lists etc, as well useful tools like grading, reports, integration with other systems and so on.<br />
<br />
For more about Moodle, see http://moodle.org, and particularly the main community “course” called [http://moodle.org/course/view.php?id=5 Using Moodle]. It's crowded and busy these days, but jump in and you'll soon find interesting stuff I'm sure. The developers and the users are deliberately forced to mix in the same forums. The other great place to start is our [https://docs.moodle.org/ online documentation] which is a community-developed wiki site.<br />
<br />
==Social Constructionism as a Referent==<br />
<br />
I have these five points on a slide which I use in every presentation I do. They are useful referents taken from research that apply to education in general, boiled down into a simple list that I carry around under the moniker of "social constructionism".<br />
<br />
# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''.<br /><br /> It's so important to recognise and remember this.<br /><br /> I think this perspective helps us retain some humility as teachers and fight the (very natural!) tendency to consolidate all your history and assume the revered position of “wise source of knowledge”.<br /><br /> It helps us keep our eyes open for opportunities to allow the other participants in our learning situation to share their ideas with us and to remind us to listen carefully and ask good questions that elicit more from others.<br /><br /> I find I need to constantly remind myself of this point, especially when the culture of a situation pushes me into a central role (like now!)<br /><br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see.'''<br /><br /> For most of us this is basically “learning by doing”, and is fairly obvious, yet it's worth reminding ourselves of it. <br /><br /> It's surprising how much online learning is still just presenting static information, giving students little opportunity to practice the activities they are learning about. I often see online teachers spending a great deal of time constructing perfect resources for their course, which no doubt is a terrific learning experience for them, but then they deny their students that same learning experience. Even textbooks often do a better job, with exercises after every chapter and so on.<br /><br /> Most importantly, such learning is best when you are expressing and presenting posts, projects, assignments, constructions etc '''for others to see'''. In this situation your personal “stakes” are a lot higher, and a lot of self-checking and reflection takes place that increases learning. Seymour Papert (the inventor of logo) famously described the process of constructing something for others to see as a very powerful learning experience, and really this sort of thinking goes right back to Socrates and beyond.<br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''.<br /><br /> Basically this is about “classroom culture”, or learning by osmosis. Humans are good at watching each other and learning what to do in a given situation though cues from others. <br /><br /> For example, if you walk into a lecture theatre where everyone is sitting in seats, facing the front, listening quietly to the teacher at the front and taking notes, then that's most likely what you are going to do too, right?<br /><br /> If you are in a less rigid class where people are asking questions all the time, then it's likely you'll feel freer to do so too. By doing so you'll be learning about both the subject itself and the meta-subject of how learning occurs from overhearing the discussions of your peers and the kinds of questions that get asked, leading to a richer multi-dimensional immersion in learning.<br /><br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> As you probably know from experience, advice from a mentor or friend can provide better, more timely and customised learning experience than with someone who doesn't know you and is speaking to a hundred people.<br /><br /> If we understand the background of the people we are speaking to then we can customise our language and our expression of concepts in ways that are best suited to the audience. You can choose metaphors that you know the audience will relate to. You can use jargon where it helps or avoid jargon when it gets in the way.<br /><br /> Again this is a pretty basic idea - every guide to public speaking talks about knowing your audience - but in online learning we need to be particular mindful of this because we often have not met these people in person and don't have access to many visual and auditory cues.<br /><br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''.<br /><br /> Combining all the above, if you as a learning facilitator want to take advantage of your growing knowledge about your participants, giving them tailored opportunities to share ideas, ask questions and express their knowledge, then you need an environment which is flexible, both in time and space.<br /><br /> If you discover that you need to throw your schedule out the window because your participants know a lot less than you'd expected when you first designed the course, you should be able to readjust the schedule, and easily add new activities to help everyone (or just one group) catch up. Likewise, some great ideas for a simulation or something may have come up during discussions, so you should be able to add those later in the course.<br /><br /> Timewise, your participants may be spread over different timezones, or maybe they live in the same timezone but have differing free time, so you should be able to offer asynchronous activities where people can work together but at different times.<br /><br /><br />
<br />
Jason Cole from Open University recently referred to these as “Martin's five laws” (ha!) but really they are referents: guiding concepts that I personally find useful to refer to whenever I need to make a decision in any given educational situation. In particular I find them useful for building '''communities of learners'''.<br />
<br />
I guess you probably find a lot of this familiar, even if you use different terms. If not there is a lot of research about constructionism, constructivism and social Constructionism which you can find out more about in some of [http://dougiamas.com/writing/ my more formal papers].<br />
<br />
==How Moodle tries to support a Social Constructionist view==<br />
<br />
I'm going to go through the earlier list again, this time pointing out existing features in Moodle. Pedagogy and software design are closely intertwined in online learning - the "shape" of the software can help or hinder the teacher in what they are trying to do.<br />
<br />
# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''<br /><br /> Many of the activities in Moodle are designed to allow students to control common content, such as forums, wikis, glossaries, databases, messaging and so on. This encourages students to add to the total course experience for others.<br /><br /> In Moodle 1.7 (just about to be released) we've made a huge step of a whole new Roles implementation which further breaks down the distinction of teachers and students, allowing Moodle system administrators and teachers to create new roles with any mix of capabilities they like. If you want students to be allowed to facilitate forums, create quiz questions or even control the course layout then you can. There is a very fine degree of control – for example you can allow students the ability to delete posts in just one single forum if you like.<br /><br /> I hope that people will take these new features and experiment with control in their courses, allowing students more flexibility to do things that were previously thought of as something teachers should do.<br /><br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see'''<br /><br /> Moodle has a wide range of ways in which people can create representations of their knowledge and share them.<br /><br /><br />
#* The course structure itself is terrific way to construct a shared and active representation of the learning journey that everyone is going through.<br />
#* Forums of course are the core of this, providing spaces for discussion and sharing of media and documents (using the media plugin filters, attachements or simply links).<br />
#* Wikis are collaboratively-built pages useful for group work and other negotiations.<br />
#* Glossaries are collaboratively-built lists of definitions that can then appear throughout the course.<br />
#* Databases are an extension of this idea allowing participants to enter structured media of any type (for example a collection of digital photos or a library of references). <br /><br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''<br /><br /> The participants page is the main place where you can see everyone in your course. It shows a lot of information about your participants and how recently they've been there.<br /><br /> An Online Users block is the best way to see everyone else who might be on right now.<br /><br /> The Recent Activity block shows a great deal of information about what has happened recently, and via link you can see reports with more detail. Things that happened not only include changes to the course and forum posts, etc, but also things like assignment submissions and quiz attempts. Students can't see the results that other students got from these activities, but they do get some sense that everyone is submitting Assignment 1 now and this peer pressure hopefully helps those who need it.<br /><br /> Finally, almost all the modules will "tag" an entry or change with the name of the user, so that you can see who did what and when. For example, wiki pages all have a history link with full details on every edit.<br /><br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> There are many different ways to find out about people. Access to these can be decided on a site basis (different sites have different privacy policies): <br /><br /><br />
#* The user profile contains several fields where people can provide information about their background, etc. In particular there is a user profile photograph, which appears throughout Moodle whenever that person writes something. The photo links back to the profile page.<br />
#* A compendium of forum posts (and discussion starters) by that person in that course (or across the site).<br />
#* Individual blogs allow people to express things in a public but reflective way, often providing access to thinking that might not normally expressed in, say, a forum.<br />
#* Overall activity reports show all the contributions from a user in a course, including assignment submissions, glossary entries, etc.<br />
#* User log reports show detailed logs of every action taken by a person in Moodle, as well as graphs showing overall activity statistics.<br />
#* The survey module provides a variety of proven questionnaire instruments for discovering interesting information about the state of mind of the group.<br /><br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''<br /><br /><br />
#* The course page itself is the main tool for a teacher, allowing them to add/remove and structure activities as necessary. Changing the course is one button click away at any time, so the teacher can change it on a whim. In Moodle 1.7 we have now added AJAX features, so that activities, sections and blocks can all be simply dragged-and-dropped.<br />
#* The roles in Moodle 1.7 can be applied individually in every context across the site, and can be further tweaked with overrides. So if you want to create one single quiz where everyone has access to everybody's results, or allow parents of students to see parts of your course, then you can.<br />
#* Navigation around the course and site is automatically generated.<br />
#* The gradebook is automatically maintained, and reflects the activities in the course at any given time.<br />
#* There are preferences for many aspects of appearance and behaviour, at site, course and activity levels, allowing educators to fine-tune the behaviour of Moodle in many ways.<br />
#* External systems can be integrated easily, to maintain authentication, enrolments and other things, allowing Moodle to react smoothly as data in other systems is modified. <br /><br />
<br />
==Finding a balance==<br />
<br />
Before I talk about about where we are going, let me talk a little about the balance that a Course Management System (aka VLE) likes Moodle needs to achieve. One thing I found out quickly in a community like ours is that people have a wide range of expectations of online learning.<br />
<br />
At the fascist extreme there are those who want students to be highly controlled: reading resources that are revealed at set times and later sitting quizzes to prove they read those resources. I call this the rat-in-the-maze approach, or dump-and-pump.<br />
<br />
At the techno-hippy end of that spectrum there are those who want to devolve management completely, with every user running their own portfolio site, streaming blogs and files to each other using RSS and trackbacks. It's an interesting dream that really opens up thinking about education but I think the problems to be solved are many (such as security, accountability, the structure of institutions etc).<br />
<br />
The vast majority of people that I meet fall somewhere between these two extremes. Many of them are new to online learning, and are looking for the next step beyond what they were being paid to do offline, while being accepting of gentle guidance to improving their online techniques. These people are on a steep learning curve already without facing the aggregation of 100 different blogs.<br />
<br />
Moodle needs to be flexible to cater for a wide variety of needs while remaining simple enough for ordinary teachers to start making good use of the power of the internet for community building and collaborative learning. My hope is that Moodle can be seen as a toolbox where they can start simply and naturally, and then progress to more and more advanced community facilitiation over time.<br />
<br />
==Where Moodle can do better and what we're doing about it==<br />
<br />
Keeping in mind the theme of this paper and the conference stream, here are a few of the upcoming plans for things that are more related to pedagogy:<br />
<br />
===Repository===<br />
<br />
Currently only teachers can upload and manage '''collections''' of files into Moodle, using the Files tool in each course. There is no easy way to share files between courses, and no way for ordinary users to keep a portfolio, say.<br />
<br />
This is changing by early next year with the addition of a Repository API (developed by Open University) that will allow Moodle to use any external repository as a place to store, browse and view files. Special-purpose repositories are a growing area, and it means institutions can keep their valuable data where they want to, even if they switch front-end systems like VLEs.<br />
<br />
Most importantly, this will make the development of e-Portfolios much easier, and these are something I think a lot of us really want to see as a very positive pedagogical enhancement.<br />
<br />
===Community Hubs===<br />
<br />
We want to improve the way teachers and users of Moodle communicate with each other, not only about e-learning and Moodle, but also in their subject areas. For example, imagine a Biology 101 teacher finding a "community" button in their course, taking them straight to a place where their peers are all discussing best practice for teaching Biology 101, sharing and browsing repositories of course materials and learning designs.<br />
<br />
A major focus for Moodle 2.0 is the creation of networking between Moodles, allowing anyone to turn their Moodle site into a Moodle Community Hub. Login between Moodles will be transparent but secure and fully controlled by site administrators. The peer-to-peer nature of the design will allow all sorts of interesting scenarios to develop.<br />
<br />
===Better interaction between tools===<br />
<br />
Currently Moodle already sends an email as notification of a lot of different types of events, but it can be difficult to manage. By piping all the messaging from throughout the system via the Messaging module that we already have, users will have a much finer control over exactly what sorts of messages they want to see. We can also allow email to come back into Moodle.<br />
<br />
Similarly, we'll be integrating the existing blogging much more tightly with the whole system, by adding "blog this" buttons everywhere that allow users to capture and comment on items of interest.<br />
<br />
===Metadata and outcome statements===<br />
<br />
Currently Moodle courses need to be manually connected to state learning standards. In many places of the world such reporting is mandatory, so it can take a lot of time.<br />
<br />
The plan for Moodle 2.0 is to include a mechanism so that:<br />
<br />
# admins can import a long list of outcome statements (as tags)<br />
# teachers can relate a subset of these to their course<br />
# teachers can connect each activity to an even smaller subset<br />
<br />
This helps course design by providing teachers with a tool to ensure the requirements for the course are being met, while also providing much better reporting for admins and students on what has been achieved.<br />
<br />
===Role-playing and scenario simulations===<br />
<br />
A popular and effective technique in face-to-face teaching is that of role-playing in scenarios, and this can be difficult to do online. You could imagine an Environmental Science course running a role-playing simulation where some students play the government, some as Greenpeace, some as industry for a particular scenario.<br />
<br />
The plans for this have been around for a long time, but I hope it can be developed soon. It would be a module where people can be assigned roles within a simulated situation and appear to others anonymously in those roles, interacting in forums, wikis, and all the other tools in Moodle according to the rules of the simulation.<br />
<br />
===Accessibility===<br />
<br />
We've spent a lot of effort making Moodle work well for those with disabilities, but we still don't have full certification against international standards. This is the major focus for Moodle 1.8, to be released in very early 2007.<br />
<br />
==What else would you like to see?==<br />
<br />
I hope this has stimulated some thoughts about the sorts of things you would like to see in your ideal online learning environment. If so, please join in with the discussions on http://moodle.org and let's brainstorm them a bit. I hope we can come up with some new ideas to put in the [http://tracker.moodle.org Moodle Tracker], or at least some support or modifications for old ones.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Pedagogy&diff=18260Pedagogy2006-11-29T15:05:13Z<p>Delius: /* Where Moodle can do better and what we're doing about it */ Fixing some typos</p>
<hr />
<div>Let's sit back and really reflect on the pedagogy that is at the core of what we, as online educators, are trying to do.<br />
<br />
==Moodle in three short paragraphs==<br />
<br />
The heart of Moodle is courses that contain activities and resources. There are about 20 different types of activities available (forums, glossaries, wikis, assignments, quizzes, choices (polls), scorm players, databases etc) and each can be customised quite a lot. The main power of this activity-based model comes in combining the activities into sequences and groups, which can help you guide participants through learning paths. Thus, each activity can build on the outcomes of previous ones.<br />
<br />
There are a number of other tools that make it easier to build communities of learners, including blogs, messaging, participant lists etc, as well useful tools like grading, reports, integration with other systems and so on.<br />
<br />
For more about Moodle, see http://moodle.org, and particularly the main community “course” called [http://moodle.org/course/view.php?id=5 Using Moodle]. It's crowded and busy these days, but jump in and you'll soon find interesting stuff I'm sure. The developers and the users are deliberately forced to mix in the same forums. The other great place to start is our [https://docs.moodle.org/ online documentation] which is a community-developed wiki site.<br />
<br />
==Social Constructionism as a Referent==<br />
<br />
I have these five points on a slide which I use in every presentation I do. They are useful referents taken from research that apply to education in general, boiled down into a simple list that I carry around under the moniker of "social constructionism".<br />
<br />
# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''.<br /><br /> It's so important to recognise and remember this.<br /><br /> I think this perspective helps us retain some humility as teachers and fight the (very natural!) tendency to consolidate all your history and assume the revered position of “wise source of knowledge”.<br /><br /> It helps us keep our eyes open for opportunities to allow the other participants in our learning situation to share their ideas with us and to remind us to listen carefully and ask good questions that elicit more from others.<br /><br /> I find I need to constantly remind myself of this point, especially when the culture of a situation pushes me into a central role (like now!)<br /><br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see.'''<br /><br /> For most of us this is basically “learning by doing”, and is fairly obvious, yet it's worth reminding ourselves of it. <br /><br /> It's surprising how much online learning is still just presenting static information, giving students little opportunity to practice the activities they are learning about. I often see online teachers spending a great deal of time constructing perfect resources for their course, which no doubt is a terrific learning experience for them, but then they deny their students that same learning experience. Even textbooks often do a better job, with exercises after every chapter and so on.<br /><br /> Most importantly, such learning is best when you are expressing and presenting posts, projects, assignments, constructions etc '''for others to see'''. In this situation your personal “stakes” are a lot higher, and a lot of self-checking and reflection takes place that increases learning. Seymour Papert (the inventor of logo) famously described the process of constructing something for others to see as a very powerful learning experience, and really this sort of thinking goes right back to Socrates and beyond.<br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''.<br /><br /> Basically this is about “classroom culture”, or learning by osmosis. Humans are good at watching each other and learning what to do in a given situation though cues from others. <br /><br /> For example, if you walk into a lecture theatre where everyone is sitting in seats, facing the front, listening quietly to the teacher at the front and taking notes, then that's most likely what you are going to do too, right?<br /><br /> If you are in a less rigid class where people are asking questions all the time, then it's likely you'll feel freer to do so too. By doing so you'll be learning about both the subject itself and the meta-subject of how learning occurs from overhearing the discussions of your peers and the kinds of questions that get asked, leading to a richer multi-dimensional immersion in learning.<br /><br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> As you probably know from experience, advice from a mentor or friend can provide better, more timely and customised learning experience than with someone who doesn't know you and is speaking to a hundred people.<br /><br /> If we understand the background of the people we are speaking to then we can customise our language and our expression of concepts in ways that are best suited to the audience. You can choose metaphors that you know the audience will relate to. You can use jargon where it helps or avoid jargon when it gets in the way.<br /><br /> Again this is a pretty basic idea - every guide to public speaking talks about knowing your audience - but in online learning we need to be particular mindful of this because we often have not met these people in person and don't have access to many visual and auditory cues.<br /><br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''.<br /><br /> Combining all the above, if you as a learning facilitator want to take advantage of your growing knowledge about your participants, giving them tailored opportunities to share ideas, ask questions and express their knowledge, then you need an environment which is flexible, both in time and space.<br /><br /> If you discover that you need to throw your schedule out the window because your participants know a lot less than you'd expected when you first designed the course, you should be able to readjust the schedule, and easily add new activities to help everyone (or just one group) catch up. Likewise, some great ideas for a simulation or something may have come up during discussions, so you should be able to add those later in the course.<br /><br /> Timewise, your participants may be spread over different timezones, or maybe they live in the same timezone but have differing free time, so you should be able to offer asynchronous activities where people can work together but at different times.<br /><br /><br />
<br />
Jason Cole from Open University recently referred to these as “Martin's five laws” (ha!) but really they are referents: guiding concepts that I personally find useful to refer to whenever I need to make a decision in any given educational situation. In particular I find them useful for building '''communities of learners'''.<br />
<br />
I guess you probably find a lot of this familiar, even if you use different terms. If not there is a lot of research about constructionism, constructivism and social Constructionism which you can find out more about in some of [http://dougiamas.com/writing/ my more formal papers].<br />
<br />
==How Moodle tries to support a Social Constructionist view==<br />
<br />
I'm going to go through the earlier list again, this time pointing out existing features in Moodle. Pedagogy and software design are closely intertwined in online learning - the "shape" of the software can help or hinder the teacher in what they are trying to do.<br />
<br />
# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''<br /><br /> Many of the activities in Moodle are designed to allow students to control common content, such as forums, wikis, glossaries, databases, messaging and so on. This encourages students to add to the total course experience for others.<br /><br /> In Moodle 1.7 (just about to be released) we've made a huge step of a whole new Roles implementation which further breaks down the distinction of teachers and students, allowing Moodle system administrators and teachers to create new roles with any mix of capabilities they like. If you want students to be allowed to facilitate forums, create quiz questions or even control the course layout then you can. There is a very fine degree of control – for example you can allow students the ability to delete posts in just one single forum if you like.<br /><br /> I hope that people will take these new features and experiment with control in their courses, allowing students more flexibility to do things that were previously thought of as something teachers should do.<br /><br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see'''<br /><br /> Moodle has a wide range of ways in which people can create representations of their knowledge and share them.<br /><br /><br />
#* The course structure itself is terrific way to construct a shared and active representation of the learning journey that everyone is going through.<br />
#* Forums of course are the core of this, providing spaces for discussion and sharing of media and documents (using the media plugin filters, attachements or simply links).<br />
#* Wikis are collaboratively-built pages useful for group work and other negotiations.<br />
#* Glossaries are collaboratively-built lists of definitions that can then appear throughout the course.<br />
#* Databases are an extension of this idea allowing participants to enter structured media of any type (for example a collection of digital photos or a library of references). <br /><br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''<br /><br /> The participants page is the main place where you can see everyone in your course. It shows a lot of information about your participants and how recently they've been there.<br /><br /> An Online Users block is the best way to see everyone else who might be on right now.<br /><br /> The Recent Activity block shows a great deal of information about what has happened recently, and via link you can see reports with more detail. Things that happened not only include changes to the course and forum posts, etc, but also things like assignment submissions and quiz attempts. Students can't see the results that other students got from these activities, but they do get some sense that everyone is submitting Assignment 1 now and this peer pressure hopefully helps those who need it.<br /><br /> Finally, almost all the modules will "tag" an entry or change with the name of the user, so that you can see who did what and when. For example, wiki pages all have a history link with full details on every edit.<br /><br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> There are many different ways to find out about people. Access to these can be decided on a site basis (different sites have different privacy policies): <br /><br /><br />
#* The user profile contains several fields where people can provide information about their background, etc. In particular there is a user profile photograph, which appears throughout Moodle whenever that person writes something. The photo links back to the profile page.<br />
#* A compendium of forum posts (and discussion starters) by that person in that course (or across the site).<br />
#* Individual blogs allow people to express things in a public but reflective way, often providing access to thinking that might not normally expressed in, say, a forum.<br />
#* Overall activity reports show all the contributions from a user in a course, including assignment submissions, glossary entries, etc.<br />
#* User log reports show detailed logs of every action taken by a person in Moodle, as well as graphs showing overall activity statistics.<br />
#* The survey module provides a variety of proven questionnaire instruments for discovering interesting information about the state of mind of the group.<br /><br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''<br /><br /><br />
#* The course page itself is the main tool for a teacher, allowing them to add/remove and structure activities as necessary. Changing the course is one button click away at any time, so the teacher can change it on a whim. In Moodle 1.7 we have now added AJAX features, so that activities, sections and blocks can all be simply dragged-and-dropped.<br />
#* The roles in Moodle 1.7 can be applied individually in every context across the site, and can be further tweaked with overrides. So if you want to create one single quiz where everyone has access to everybody's results, or allow parents of students to see parts of your course, then you can.<br />
#* Navigation around the course and site is automatically generated.<br />
#* The gradebook is automatically maintained, and reflects the activities in the course at any given time.<br />
#* There are preferences for many aspects of appearance and behaviour, at site, course and activity levels, allowing educators to fine-tune the behaviour of Moodle in many ways.<br />
#* External systems can be integrated easily, to maintain authentication, enrolments and other things, allowing Moodle to react smoothly as data in other systems is modified. <br /><br />
<br />
==Finding a balance==<br />
<br />
Before I talk about about where we are going, let me talk a little about the balance that a Course Management System (aka VLE) likes Moodle needs to achieve. One thing I found out quickly in a community like ours is that people have a wide range of expectations of online learning.<br />
<br />
At the fascist extreme there are those who want students to be highly controlled: reading resources that are revealed at set times and later sitting quizzes to prove they read those resources. I call this the rat-in-the-maze approach, or dump-and-pump.<br />
<br />
At the techno-hippy end of that spectrum there are those who want to devolve management completely, with every user running their own portfolio site, streaming blogs and files to each other using RSS and trackbacks. It's an interesting dream that really opens up thinking about education but I think the problems to be solved are many (such as security, accountability, the structure of institutions etc).<br />
<br />
The vast majority of people that I meet fall somewhere between these two extremes. Many of them are new to online learning, and are looking for the next step beyond what they were being paid to do offline, while being accepting of gentle guidance to improving their online techniques. These people are on a steep learning curve already without facing the aggregation of 100 different blogs.<br />
<br />
Moodle needs to be flexible to cater for a wide variety of needs while remaining simple enough for ordinary teachers to start making good use of the power of the internet for community building and collaborative learning. My hope is that Moodle can be seen as a toolbox where they can start simply and naturally, and then progress to more and more advanced community facilitiation over time.<br />
<br />
==Where Moodle can do better and what we're doing about it==<br />
<br />
Keeping in mind the theme of this paper and the conference stream, here are a few of the upcoming plans for things that are more pedagogically-related:<br />
<br />
===Repository===<br />
<br />
Currently only teachers can upload and manage '''collections''' of files into Moodle, using the Files tool in each course. There is no easy way to share files between courses, and no way for ordinary users to keep a portfolio, say.<br />
<br />
This is changing by early next year with the addition of a Repository API (developed by Open University) that will allow Moodle to use any external repository as a place to store, browse and view files. Special-purpose repositories are a growing area, and it means institutions can keep their valuable data where they want to, even if they switch front-end systems like VLEs.<br />
<br />
Most importantly, this will make the development of e-Portfolios much easier, and these are something I think a lot of us really want to see as a very positive pedagogical enhancement.<br />
<br />
===Community Hubs===<br />
<br />
We want to improve the way teachers and users of Moodle communicate with each other, not only about e-learning and Moodle, but also in their subject areas. For example, imagine a Biology 101 teacher finding a "community" button in their course, taking them straight to a place where their peers are all discussing best practice for teaching Biology 101, sharing and browsing repositories of course materials and learning designs.<br />
<br />
A major focus for Moodle 2.0 is the creation of networking between Moodles, allowing anyone to turn their Moodle site into a Moodle Community Hubs. Login between Moodles will be transparent but secure and fully controlled by site administrators. The peer-to-peer nature of the design will allow all sorts of interesting scenarios to develop.<br />
<br />
===Better interaction between tools===<br />
<br />
Currently Moodle already sends a email as notification of a lot of different types of events, but it can be difficult to manage. By piping all the messaging from throughout the system via the Messaging module that we already have, users will have a much finer control over exactly what sorts of messages they want to see. We can also allow email to come back into Moodle.<br />
<br />
Similarly, we'll be integrating the existing blogging much more tightly with the whole system, by adding "blog this" buttons everywhere that allow users to capture and comment on items of interest.<br />
<br />
===Metadata and outcome statements===<br />
<br />
Currently Moodle courses need to be manually connected to state learning standards. In many places of the world such reporting is mandatory, so it can take a lot of time.<br />
<br />
The plan for Moodle 2.0 is to include a mechanism so that:<br />
<br />
# admins can import a long list of outcome statements (as tags)<br />
# teachers can relate a subset of these to their course<br />
# teachers can connect each activity to an even smaller subset<br />
<br />
This helps course design by providing teachers with a tool to ensure the requirements for the course are being met, while also providing much better reporting for admins and students on what has been achieved.<br />
<br />
===Role-playing and scenario simulations===<br />
<br />
A popular and effective technique in face-to-face teaching is that of role-playing in scenarios, and this can be difficult to do online. You could imagine an Environmental Science course running a role-playing simulation where some students play the government, some as Greenpeace, some as industry for a particular scenario.<br />
<br />
The plans for this have been around for a long time, but I hope it can be developed soon. It would be a module where people can be assigned roles within a simulated situation and appear to others anonymously in those roles, interacting in forums, wikis, and all the other tools in Moodle according to the rules of the simulation.<br />
<br />
===Accessibility===<br />
<br />
We've spent a lot of effort making Moodle work well for those with disabilities, but we still don't have full certification against international standards. This is the major focus for Moodle 1.8, to be released in very early 2007.<br />
<br />
==What else would you like to see?==<br />
<br />
I hope this has stimulated some thoughts about the sorts of things you would like to see in your ideal online learning environment. If so, please join in with the discussions on http://moodle.org and let's brainstorm them a bit. I hope we can come up with some new ideas to put in the [http://tracker.moodle.org Moodle Tracker], or at least some support or modifications for old ones.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Pedagogy&diff=18259Pedagogy2006-11-29T15:04:04Z<p>Delius: /* Where Moodle can do better and we're doing about it */ Fixing typo (missing word)</p>
<hr />
<div>Let's sit back and really reflect on the pedagogy that is at the core of what we, as online educators, are trying to do.<br />
<br />
==Moodle in three short paragraphs==<br />
<br />
The heart of Moodle is courses that contain activities and resources. There are about 20 different types of activities available (forums, glossaries, wikis, assignments, quizzes, choices (polls), scorm players, databases etc) and each can be customised quite a lot. The main power of this activity-based model comes in combining the activities into sequences and groups, which can help you guide participants through learning paths. Thus, each activity can build on the outcomes of previous ones.<br />
<br />
There are a number of other tools that make it easier to build communities of learners, including blogs, messaging, participant lists etc, as well useful tools like grading, reports, integration with other systems and so on.<br />
<br />
For more about Moodle, see http://moodle.org, and particularly the main community “course” called [http://moodle.org/course/view.php?id=5 Using Moodle]. It's crowded and busy these days, but jump in and you'll soon find interesting stuff I'm sure. The developers and the users are deliberately forced to mix in the same forums. The other great place to start is our [https://docs.moodle.org/ online documentation] which is a community-developed wiki site.<br />
<br />
==Social Constructionism as a Referent==<br />
<br />
I have these five points on a slide which I use in every presentation I do. They are useful referents taken from research that apply to education in general, boiled down into a simple list that I carry around under the moniker of "social constructionism".<br />
<br />
# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''.<br /><br /> It's so important to recognise and remember this.<br /><br /> I think this perspective helps us retain some humility as teachers and fight the (very natural!) tendency to consolidate all your history and assume the revered position of “wise source of knowledge”.<br /><br /> It helps us keep our eyes open for opportunities to allow the other participants in our learning situation to share their ideas with us and to remind us to listen carefully and ask good questions that elicit more from others.<br /><br /> I find I need to constantly remind myself of this point, especially when the culture of a situation pushes me into a central role (like now!)<br /><br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see.'''<br /><br /> For most of us this is basically “learning by doing”, and is fairly obvious, yet it's worth reminding ourselves of it. <br /><br /> It's surprising how much online learning is still just presenting static information, giving students little opportunity to practice the activities they are learning about. I often see online teachers spending a great deal of time constructing perfect resources for their course, which no doubt is a terrific learning experience for them, but then they deny their students that same learning experience. Even textbooks often do a better job, with exercises after every chapter and so on.<br /><br /> Most importantly, such learning is best when you are expressing and presenting posts, projects, assignments, constructions etc '''for others to see'''. In this situation your personal “stakes” are a lot higher, and a lot of self-checking and reflection takes place that increases learning. Seymour Papert (the inventor of logo) famously described the process of constructing something for others to see as a very powerful learning experience, and really this sort of thinking goes right back to Socrates and beyond.<br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''.<br /><br /> Basically this is about “classroom culture”, or learning by osmosis. Humans are good at watching each other and learning what to do in a given situation though cues from others. <br /><br /> For example, if you walk into a lecture theatre where everyone is sitting in seats, facing the front, listening quietly to the teacher at the front and taking notes, then that's most likely what you are going to do too, right?<br /><br /> If you are in a less rigid class where people are asking questions all the time, then it's likely you'll feel freer to do so too. By doing so you'll be learning about both the subject itself and the meta-subject of how learning occurs from overhearing the discussions of your peers and the kinds of questions that get asked, leading to a richer multi-dimensional immersion in learning.<br /><br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> As you probably know from experience, advice from a mentor or friend can provide better, more timely and customised learning experience than with someone who doesn't know you and is speaking to a hundred people.<br /><br /> If we understand the background of the people we are speaking to then we can customise our language and our expression of concepts in ways that are best suited to the audience. You can choose metaphors that you know the audience will relate to. You can use jargon where it helps or avoid jargon when it gets in the way.<br /><br /> Again this is a pretty basic idea - every guide to public speaking talks about knowing your audience - but in online learning we need to be particular mindful of this because we often have not met these people in person and don't have access to many visual and auditory cues.<br /><br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''.<br /><br /> Combining all the above, if you as a learning facilitator want to take advantage of your growing knowledge about your participants, giving them tailored opportunities to share ideas, ask questions and express their knowledge, then you need an environment which is flexible, both in time and space.<br /><br /> If you discover that you need to throw your schedule out the window because your participants know a lot less than you'd expected when you first designed the course, you should be able to readjust the schedule, and easily add new activities to help everyone (or just one group) catch up. Likewise, some great ideas for a simulation or something may have come up during discussions, so you should be able to add those later in the course.<br /><br /> Timewise, your participants may be spread over different timezones, or maybe they live in the same timezone but have differing free time, so you should be able to offer asynchronous activities where people can work together but at different times.<br /><br /><br />
<br />
Jason Cole from Open University recently referred to these as “Martin's five laws” (ha!) but really they are referents: guiding concepts that I personally find useful to refer to whenever I need to make a decision in any given educational situation. In particular I find them useful for building '''communities of learners'''.<br />
<br />
I guess you probably find a lot of this familiar, even if you use different terms. If not there is a lot of research about constructionism, constructivism and social Constructionism which you can find out more about in some of [http://dougiamas.com/writing/ my more formal papers].<br />
<br />
==How Moodle tries to support a Social Constructionist view==<br />
<br />
I'm going to go through the earlier list again, this time pointing out existing features in Moodle. Pedagogy and software design are closely intertwined in online learning - the "shape" of the software can help or hinder the teacher in what they are trying to do.<br />
<br />
# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''<br /><br /> Many of the activities in Moodle are designed to allow students to control common content, such as forums, wikis, glossaries, databases, messaging and so on. This encourages students to add to the total course experience for others.<br /><br /> In Moodle 1.7 (just about to be released) we've made a huge step of a whole new Roles implementation which further breaks down the distinction of teachers and students, allowing Moodle system administrators and teachers to create new roles with any mix of capabilities they like. If you want students to be allowed to facilitate forums, create quiz questions or even control the course layout then you can. There is a very fine degree of control – for example you can allow students the ability to delete posts in just one single forum if you like.<br /><br /> I hope that people will take these new features and experiment with control in their courses, allowing students more flexibility to do things that were previously thought of as something teachers should do.<br /><br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see'''<br /><br /> Moodle has a wide range of ways in which people can create representations of their knowledge and share them.<br /><br /><br />
#* The course structure itself is terrific way to construct a shared and active representation of the learning journey that everyone is going through.<br />
#* Forums of course are the core of this, providing spaces for discussion and sharing of media and documents (using the media plugin filters, attachements or simply links).<br />
#* Wikis are collaboratively-built pages useful for group work and other negotiations.<br />
#* Glossaries are collaboratively-built lists of definitions that can then appear throughout the course.<br />
#* Databases are an extension of this idea allowing participants to enter structured media of any type (for example a collection of digital photos or a library of references). <br /><br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''<br /><br /> The participants page is the main place where you can see everyone in your course. It shows a lot of information about your participants and how recently they've been there.<br /><br /> An Online Users block is the best way to see everyone else who might be on right now.<br /><br /> The Recent Activity block shows a great deal of information about what has happened recently, and via link you can see reports with more detail. Things that happened not only include changes to the course and forum posts, etc, but also things like assignment submissions and quiz attempts. Students can't see the results that other students got from these activities, but they do get some sense that everyone is submitting Assignment 1 now and this peer pressure hopefully helps those who need it.<br /><br /> Finally, almost all the modules will "tag" an entry or change with the name of the user, so that you can see who did what and when. For example, wiki pages all have a history link with full details on every edit.<br /><br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> There are many different ways to find out about people. Access to these can be decided on a site basis (different sites have different privacy policies): <br /><br /><br />
#* The user profile contains several fields where people can provide information about their background, etc. In particular there is a user profile photograph, which appears throughout Moodle whenever that person writes something. The photo links back to the profile page.<br />
#* A compendium of forum posts (and discussion starters) by that person in that course (or across the site).<br />
#* Individual blogs allow people to express things in a public but reflective way, often providing access to thinking that might not normally expressed in, say, a forum.<br />
#* Overall activity reports show all the contributions from a user in a course, including assignment submissions, glossary entries, etc.<br />
#* User log reports show detailed logs of every action taken by a person in Moodle, as well as graphs showing overall activity statistics.<br />
#* The survey module provides a variety of proven questionnaire instruments for discovering interesting information about the state of mind of the group.<br /><br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''<br /><br /><br />
#* The course page itself is the main tool for a teacher, allowing them to add/remove and structure activities as necessary. Changing the course is one button click away at any time, so the teacher can change it on a whim. In Moodle 1.7 we have now added AJAX features, so that activities, sections and blocks can all be simply dragged-and-dropped.<br />
#* The roles in Moodle 1.7 can be applied individually in every context across the site, and can be further tweaked with overrides. So if you want to create one single quiz where everyone has access to everybody's results, or allow parents of students to see parts of your course, then you can.<br />
#* Navigation around the course and site is automatically generated.<br />
#* The gradebook is automatically maintained, and reflects the activities in the course at any given time.<br />
#* There are preferences for many aspects of appearance and behaviour, at site, course and activity levels, allowing educators to fine-tune the behaviour of Moodle in many ways.<br />
#* External systems can be integrated easily, to maintain authentication, enrolments and other things, allowing Moodle to react smoothly as data in other systems is modified. <br /><br />
<br />
==Finding a balance==<br />
<br />
Before I talk about about where we are going, let me talk a little about the balance that a Course Management System (aka VLE) likes Moodle needs to achieve. One thing I found out quickly in a community like ours is that people have a wide range of expectations of online learning.<br />
<br />
At the fascist extreme there are those who want students to be highly controlled: reading resources that are revealed at set times and later sitting quizzes to prove they read those resources. I call this the rat-in-the-maze approach, or dump-and-pump.<br />
<br />
At the techno-hippy end of that spectrum there are those who want to devolve management completely, with every user running their own portfolio site, streaming blogs and files to each other using RSS and trackbacks. It's an interesting dream that really opens up thinking about education but I think the problems to be solved are many (such as security, accountability, the structure of institutions etc).<br />
<br />
The vast majority of people that I meet fall somewhere between these two extremes. Many of them are new to online learning, and are looking for the next step beyond what they were being paid to do offline, while being accepting of gentle guidance to improving their online techniques. These people are on a steep learning curve already without facing the aggregation of 100 different blogs.<br />
<br />
Moodle needs to be flexible to cater for a wide variety of needs while remaining simple enough for ordinary teachers to start making good use of the power of the internet for community building and collaborative learning. My hope is that Moodle can be seen as a toolbox where they can start simply and naturally, and then progress to more and more advanced community facilitiation over time.<br />
<br />
==Where Moodle can do better and what we're doing about it==<br />
<br />
Keeping in mind the theme of this paper and the conference stream, here are a few of the upcoming plans for things that are more pegadogically-related:<br />
<br />
===Repository===<br />
<br />
Currently only teachers can upload and manage '''collections''' of files into Moodle, using the Files tool in each course. There is no easy way to share files between courses, and no way for ordinary users to keep a portfolio, say.<br />
<br />
This is changing by early next year with the addition of a Repository API (developed by Open University) that will allow Moodle to use any external repository as a place to store, browse and view files. Special-purpose repositories are a growing area, and it means insitutions can keep their valuable data where they want to, even if they switch front-end systems like VLEs.<br />
<br />
Most importantly, this will make the development of e-Portfolios much easier, and these are something I think a lot of us really want to see as a very positive pedagogical enhancement.<br />
<br />
===Community Hubs===<br />
<br />
We want to improve the way teachers and users of Moodle communicate with each other, not only about e-learning and Moodle, but also in their subject areas. For example, imagine a Biology 101 teacher finding a "community" button in their course, taking them straight to a place where their peers are all discussing best practice for teaching Biology 101, sharing and browsing repositories of course materials and learning designs.<br />
<br />
A major focus for Moodle 2.0 is the creation of networking between Moodles, allowing anyone to turn their Moodle site into a Moodle Community Hubs. Login between Moodles will be transparent but secure and fully controlled by site administrators. The peer-to-peer nature of the design will allow all sorts of interesting scenarios to develop.<br />
<br />
===Better interaction between tools===<br />
<br />
Currently Moodle already sends a email as notification of a lot of different types of events, but it can be difficult to manage. By piping all the messaging from throughout the system via the Messaging module that we already have, users will have a much finer control over exactly what sorts of messages they want to see. We can also allow email to come back into Moodle.<br />
<br />
Similarly, we'll be integrating the existing blogging much more tightly with the whole system, by adding "blog this" buttons everywhere that allow users to capture and comment on items of interest.<br />
<br />
===Metadata and outcome statements===<br />
<br />
Currently Moodle courses need to be manually connected to state learning standards. In many places of the world such reporting is mandatory, so it can take a lot of time.<br />
<br />
The plan for Moodle 2.0 is to include a mechanism so that:<br />
<br />
# admins can import a long list of outcome statements (as tags)<br />
# teachers can relate a subset of these to their course<br />
# teachers can connect each activity to an even smaller subset<br />
<br />
This helps course design by providing teachers with a tool to ensure the requirements for the course are being met, while also providing much better reporting for admins and students on what has been achieved.<br />
<br />
===Role-playing and scenario simulations===<br />
<br />
A popular and effective technique in face-to-face teaching is that of role-playing in scenarios, and this can be difficult to do online. You could imagine an Environmental Science course running a role-playing simulation where some students play the government, some as Greenpeace, some as industry for a particular scenario.<br />
<br />
The plans for this have been around for a long time, but I hope it can be developed soon. It would be a module where people can be assigned roles within a simulated situation and appear to others anonymously in those roles, interacting in forums, wikis, and all the other tools in Moodle according to the rules of the simulation.<br />
<br />
===Accessibility===<br />
<br />
We've spent a lot of effort making Moodle work well for those with disabilities, but we still don't have full certification against international standards. This is the major focus for Moodle 1.8, to be released in very early 2007.<br />
<br />
==What else would you like to see?==<br />
<br />
I hope this has stimulated some thoughts about the sorts of things you would like to see in your ideal online learning environment. If so, please join in with the discussions on http://moodle.org and let's brainstorm them a bit. I hope we can come up with some new ideas to put in the [http://tracker.moodle.org Moodle Tracker], or at least some support or modifications for old ones.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Performance_recommendations&diff=17001Performance recommendations2006-10-13T16:26:23Z<p>Delius: /* Database performance */ Taking out unrelated link</p>
<hr />
<div>Moodle can be made to perform very well, at small usage levels or scaling up to many thousands of users. The factors involved in performance are basically the same as for any PHP-based database-driven system, and Moodle's design (with clear separation of application layers) allows for strongly scalable setups. (Please check the list of [[Large installations|large Moodle installations]].)<br />
<br />
Large sites usually separate the web server and database onto separate servers, although for smaller installations this is typically not necessary.<br />
<br />
It is possible to load-balance a Moodle installation, for example by using more than one webserver. The separate webservers should query the same database and refer to the same filestore area, but otherwise the separation of the application layers is complete enough to make this kind of clustering feasible. Similarly, the database could be a cluster of servers (e.g. a MySQL cluster).<br />
<br />
:::The above comment makes it sound easy to run a database cluster. It is not. It is easy to run the webservers in cluster with LVM and other solutions. The only "easy" cluster database is MySQL Cluster and there are several issues with it. --[[User:Martin Langhoff|Martin Langhoff]] 18:53, 31 August 2006 (CDT)<br />
<br />
==Web server performance==<br />
<br />
* The amount of '''RAM''' on your web server is the strongest factor in performance - get as much as possible (eg 4GB).<br />
* Linux or Unix is the recommended '''operating system''' for the server. They perform much better than Mac OSX or Windows servers at high loads.<br />
* You are strongly recommended to use a '''PHP accelerator''' to ease CPU load, such as Turck MMCache, PHPA or eAccelerator. (Take care to choose a PHP accelerator that is known to work well with your version of PHP etc.)<br />
* Performance of PHP is better when installed as an Apache module (rather than a CGI).<br />
* On a Unix/Linux system, performance can be greatly improved by allowing the webserver to use the system '''zip/unzip''' commands (rather than PHP-based zip libraries) - visit Admin/Configure/Variables and enter the path to the relevant executables. (Similarly, filling in the path to '''du''' will improve Moodle's speed at listing directory contents.)<br />
* Note that using '''secure web connections''' ('''https''' rather than '''http''') carries a higher processing burden, both for the webserver and the client - particularly because cacheing cannot be used as effectively, so the number of file requests is likely to increase dramatically. For this reason using https for all Moodle pages is not recommended. You can enable https just for the login screen, simply from Moodle's config page.<br />
* You can increase performance by using the light-weight webserver [http://www.lighttpd.org/ lighttpd] in combination with PHP in fastCGI-mode instead of Apache, due to much lower memory consumption. One single apache process requires more RAM than the whole lighttpd with all of its fastCGI-processes together. Note that this may not be a good solution if you can afford lots of hardware power, because administration takes a little more time.<br />
* Consider lowering MaxRequestsPerChild in httpd.conf to as low as 20-30 (if you set it any lower the overhead of forking begins to outweigh the benefits). Also check the memory_limit in php.ini, reduce it to at least 16M. ([http://moodle.org/mod/forum/discuss.php?d=39656 Suggested by Rory Allford])<br />
<br />
==Database performance==<br />
<br />
* [[Arguments in favour of PostgreSQL]]<br />
* [http://dev.mysql.com/doc/refman/5.0/en/server-parameters.html Tuning MySQL parameters] (advice from the MySQL manual)<br />
<br />
==Performance of different Moodle modules==<br />
<br />
Moodle's activity modules, filters, and other plugins can be activated/deactivated. If necessary, you may wish to deactivate some features (such as chat) if not required - but this isn't necessary. Some notes on the performance of certain modules:<br />
<br />
* The '''Chat''' module is [http://moodle.org/mod/forum/discuss.php?d=37979&parent=175079 said] to be a hog in terms of frequent HTTP requests to the main server. This can be reduced by setting the module to use ''Streamed'' updates, or, if you're using a Unix-based webserver, by running the chat in daemon mode.<br />
* [http://moodle.org/mod/forum/discuss.php?d=25616&parent=120770 Brief report on performance for 55 students simultaneously using '''Quiz''']<br />
* The Moodle '''cron''' task is triggered by calling the script ''cron.php''. If this is called over HTTP (e.g. using wget or curl) it can take a large amount of memory on large installations. If it is called by directly invoking the php command (e.g. ''php -f /path/to/moodle/directory/admin/cron.php'') efficiency can be much improved.<br />
* Having too many filters active can have serious effects on server load, especially on lower-end systems. The number of active filters has a direct effect on the perceived latency of your site; that is the time taken for each page impression. For best performance, leave the text cache enabled and do not "Filter all strings" unless you have a specific need. If in doubt [[Performance profiling|profile the performance]], and see how your changes affect the processing time.<br />
<br />
==See also==<br />
<br />
*Using Moodle [http://moodle.org/mod/forum/view.php?f=94 Servers and Performance] forum<br />
<br />
[[Category:Administrator]]<br />
[[Category:Performance]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16971Development:Slashes2006-10-12T15:31:07Z<p>Delius: </p>
<hr />
<div>The functions <code>addslashes()</code> and <code>stripslashes()</code> are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the <code>addslashes()</code> function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the <code>stripslashes()</code> function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
<br />
[[Image:Stripslashes.jpg|none]]<br />
<br />
Neither <code>stripslashes()</code> nor <code>addslashes()</code> should be used when going from User Input to the Database or from the Database to Screen Output (black arrows) but <code>stripslashes()</code> should be used when displaying user input on the screen (red arrow) and <code>addslashes()</code> should be used when reinserting data in to the database that came from the database (blue arrow). These last two are rare, so the use of addslashes and stripslashes should be rare.<br />
<br />
Please note that when outputting strings from the database, you should never simply use echo or something similar but should use Moodle's [[Development:Output functions|output functions]].<br />
<br />
Sometimes you may want to add slashes or remove slashes from all proprties of an object at once. Moodle provides the very convenient functions <code>addslashes_object()</code> and <code>stripslashes_recursive()</code>. The latter also works on arrays.<br />
<br />
One thing to watch out for is that the parameter type PARAM_CLEANHTML strips slashes, so you have to add slashes before putting data cleaned this way into the database or user PARAM_CLEAN instead.<br />
<br />
Moodle provides a function called <code>stripslashes_safe()</code> which only strips slashes in front of single and double quotes and in front of a backslash, so \' becomes ', \" becomes ", and \\ becomes \. Any other slashes, as in C:\Moodle for example, are preserved. It was introduced because in some circumstances it may not matter if this function is applied too often. However I find this function dangerous, because it may make you think that everything is fine until one of your users wants to include a bit of code in their input for example. I would not have been able to write this paragraph (with the \' in it) if it had been passed through <code>stripslashes_safe()</code>.<br />
<br />
Some core Moodle functions use <code>stripslashes_safe()</code>:<br />
print_heading()<br />
print_heading_with_help()<br />
print_heading_block()<br />
print_simple_box()<br />
It usually doesn't matter too much for headings, because including \\, \', or \" in headings is unusual, but it does matter in print_simple_box() and therefore the advice would be to avoid using this function and to use the <code>print_simple_box_start()</code> and <code>print_simple_box_end()</code> pair.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16970Development:Slashes2006-10-12T15:28:20Z<p>Delius: Added comment about strange behaviour of PARAM_CLEANHTML</p>
<hr />
<div>The functions <code>addslashes()</code> and <code>stripslashes()</code> are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the <code>addslashes()</code> function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the <code>stripslashes()</code> function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
<br />
[[Image:Stripslashes.jpg|none]]<br />
<br />
Neither <code>stripslashes()</code> nor <code>addslashes()</code> should be used when going from User Input to the Database or from the Database to Screen Output (black arrows) but <code>stripslashes()</code> should be used when displaying user input on the screen (red arrow) and <code>addslashes()</code> should be used when reinserting data in to the database that came from the database (blue arrow). These last two are rare, so the use of addslashes and stripslashes should be rare.<br />
<br />
Please note that when outputting strings from the database, you should never simply use echo or something similar but should use Moodle's [[Development:Output functions|output functions]].<br />
<br />
Sometimes you may want to add slashes or remove slashes from all proprties of an object at once. Moodle provides the very convenient functions <code>addslashes_object()</code> and <code>stripslashes_recursive()</code>. The latter also works on arrays.<br />
<br />
One thing to watch out for is that the parameter type PARAM_CLEANHTML strips slashes, so you have to add slashes before putting data cleaned this way into the database.<br />
<br />
Moodle provides a function called <code>stripslashes_safe()</code> which only strips slashes in front of single and double quotes and in front of a backslash, so \' becomes ', \" becomes ", and \\ becomes \. Any other slashes, as in C:\Moodle for example, are preserved. It was introduced because in some circumstances it may not matter if this function is applied too often. However I find this function dangerous, because it may make you think that everything is fine until one of your users wants to include a bit of code in their input for example. I would not have been able to write this paragraph (with the \' in it) if it had been passed through <code>stripslashes_safe()</code>.<br />
<br />
Some core Moodle functions use <code>stripslashes_safe()</code>:<br />
print_heading()<br />
print_heading_with_help()<br />
print_heading_block()<br />
print_simple_box()<br />
It usually doesn't matter too much for headings, because including \\, \', or \" in headings is unusual, but it does matter in print_simple_box() and therefore the advice would be to avoid using this function and to use the <code>print_simple_box_start()</code> and <code>print_simple_box_end()</code> pair.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16804Development:Slashes2006-10-08T18:47:52Z<p>Delius: Added link to Development:Output functions</p>
<hr />
<div>The functions <code>addslashes()</code> and <code>stripslashes()</code> are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the <code>addslashes()</code> function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the <code>stripslashes()</code> function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
<br />
[[Image:Stripslashes.jpg|none]]<br />
<br />
Neither <code>stripslashes()</code> nor <code>addslashes()</code> should be used when going from User Input to the Database or from the Database to Screen Output (black arrows) but <code>stripslashes()</code> should be used when displaying user input on the screen (red arrow) and <code>addslashes()</code> should be used when reinserting data in to the database that came from the database (blue arrow). These last two are rare, so the use of addslashes and stripslashes should be rare.<br />
<br />
Please note that when outputting strings from the database, you should never simply use echo or something similar but should use Moodle's [[Development:Output functions|output functions]].<br />
<br />
Sometimes you may want to add slashes or remove slashes from all proprties of an object at once. Moodle provides the very convenient functions <code>addslashes_object()</code> and <code>stripslashes_recursive()</code>. The latter also works on arrays.<br />
<br />
Moodle provides a function called <code>stripslashes_safe()</code> which only strips slashes in front of single and double quotes and in front of a backslash, so \' becomes ', \" becomes ", and \\ becomes \. Any other slashes, as in C:\Moodle for example, are preserved. It was introduced because in some circumstances it may not matter if this function is applied too often. However I find this function dangerous, because it may make you think that everything is fine until one of your users wants to include a bit of code in their input for example. I would not have been able to write this paragraph (with the \' in it) if it had been passed through <code>stripslashes_safe()</code>.<br />
<br />
Some core Moodle functions use <code>stripslashes_safe()</code>:<br />
print_heading()<br />
print_heading_with_help()<br />
print_heading_block()<br />
print_simple_box()<br />
It usually doesn't matter too much for headings, because including \\, \', or \" in headings is unusual, but it does matter in print_simple_box() and therefore the advice would be to avoid using this function and to use the <code>print_simple_box_start()</code> and <code>print_simple_box_end()</code> pair.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Coding&diff=16705Development:Coding2006-10-07T12:46:30Z<p>Delius: /* Security issues (and handling form and URL data) */</p>
<hr />
<div>Any collaborative project needs consistency and stability to stay strong.<br />
<br />
These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.<br />
<br />
==General rules==<br />
<br />
# All code files should use the .php extension.<br />
# All template files should use the .html extension.<br />
# All text files should use Unix-style text format (most text editors have this as an option).<br />
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.<br />
# All existing copyright notices must be retained. You can add your own if necessary.<br />
# Each file should include the main config.php file.<br />
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().<br />
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.<br />
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.<br />
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.<br />
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().<br />
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:<br />
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.<br />
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.<br />
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].<br />
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Developer:Output_functions|output functions]].<br />
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].<br />
<br />
==Coding style==<br />
<br />
I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.<br />
<br />
1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.<br />
<br />
2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.<br />
<br />
GOOD: $quiz<br />
GOOD: $errorstring<br />
GOOD: $assignments (for an array of objects)<br />
GOOD: $i (but only in little loops)<br />
<br />
BAD: $Quiz<br />
BAD: $aReallyLongVariableNameWithoutAGoodReason<br />
BAD: $error_string<br />
<br />
3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.<br />
<br />
define("FORUM_MODE_FLATOLDEST", 1);<br />
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).<br />
<br />
function forum_set_display_mode($mode=0) {<br />
global $USER, $CFG;<br />
<br />
if ($mode) {<br />
$USER->mode = $mode;<br />
} else if (empty($USER->mode)) {<br />
$USER->mode = $CFG->forum_displaymode;<br />
}<br />
}<br />
<br />
5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:<br />
<br />
if ($quiz->attempts) {<br />
if ($numattempts > $quiz->attempts) {<br />
error($strtoomanyattempts, "view.php?id=$cm->id");<br />
}<br />
}<br />
<br />
6. Strings should be defined using single quotes where possible, for increased speed.<br />
<br />
$var = 'some text without any variables';<br />
$var = "with special characters like a new line \n";<br />
$var = 'a very, very long string with a '.$single.' variable in it';<br />
$var = "some $text with $many variables $within it";<br />
<br />
7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.<br />
<br />
* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.<br />
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.<br />
<br />
/**<br />
* The description should be first, with asterisks laid out exactly<br />
* like this example. If you want to refer to a another function,<br />
* do it like this: {@link clean_param()}. Then, add descriptions<br />
* for each parameter as follows.<br />
*<br />
* @param int $postid The PHP type is followed by the variable name<br />
* @param array $scale The PHP type is followed by the variable name<br />
* @param array $ratings The PHP type is followed by the variable name<br />
* @return mixed<br />
*/<br />
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {<br />
if (!$ratings) {<br />
$ratings = array(); // Initialize the empty array<br />
if ($rates = get_records("forum_ratings", "post", $postid)) {<br />
// Process each rating in turn<br />
foreach ($rates as $rate) {<br />
....etc<br />
<br />
8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:<br />
<br />
foreach ($objects as $key => $thing) {<br />
process($thing);<br />
}<br />
<br />
if ($x == $y) {<br />
$a = $b;<br />
} else if ($x == $z) {<br />
$a = $c;<br />
} else {<br />
$a = $d;<br />
}<br />
<br />
9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.<br />
<br />
BAD: $b = $a;<br />
GOOD: $b = clone($a);<br />
<br />
If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.<br />
<br />
==Database structures==<br />
<br />
# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])<br />
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:<br />
#* id - as described above<br />
#* course - the id of the course that each instance belongs to<br />
#* name - the full name of each instance of the module<br />
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).<br />
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.<br />
# Column names should be always lowercase, simple and short, following the same rules as for variable names.<br />
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)<br />
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.<br />
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.<br />
# Always define a default value for each field (and make it sensible)<br />
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.<br />
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):<br />
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.<br />
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.<br />
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated. <br />
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.<br />
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.<br />
<br />
==Security issues (and handling form and URL data)==<br />
<br />
# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from<br />
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.<br />
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Use data_submitted(), with care. Data must still be cleaned before use.<br />
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.<br />
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....<br />
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.<br />
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.<br />
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()<br />
# Any data read from the database must have [[Developer:Slashes|addslashes()]] applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().<br />
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).<br />
# Do not use data from $_SERVER if you can avoid it. This has portability issues.<br />
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.<br />
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.<br />
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.<br />
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.<br />
<br />
[[Category:Developer]]<br />
<br />
[[es:Manual de Estilo de Código]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16704Development:Slashes2006-10-07T12:08:44Z<p>Delius: </p>
<hr />
<div>The functions <code>addslashes()</code> and <code>stripslashes()</code> are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the <code>addslashes()</code> function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the <code>stripslashes()</code> function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
<br />
[[Image:Stripslashes.jpg|none]]<br />
<br />
Neither <code>stripslashes()</code> nor <code>addslashes()</code> should be used when going from User Input to the Database or from the Database to Screen Output (black arrows) but <code>stripslashes()</code> should be used when displaying user input on the screen (red arrow) and <code>addslashes()</code> should be used when reinserting data in to the database that came from the database (blue arrow). These last two are rare, so the use of addslashes and stripslashes should be rare.<br />
<br />
Sometimes you may want to add slashes or remove slashes from all proprties of an object at once. Moodle provides the very convenient functions <code>addslashes_object()</code> and <code>stripslashes_recursive()</code>. The latter also works on arrays.<br />
<br />
Moodle provides a function called <code>stripslashes_safe()</code> which only strips slashes in front of single and double quotes and in front of a backslash, so \' becomes ', \" becomes ", and \\ becomes \. Any other slashes, as in C:\Moodle for example, are preserved. It was introduced because in some circumstances it may not matter if this function is applied too often. However I find this function dangerous, because it may make you think that everything is fine until one of your users wants to include a bit of code in their input for example. I would not have been able to write this paragraph (with the \' in it) if it had been passed through <code>stripslashes_safe()</code>.<br />
<br />
Some core Moodle functions use <code>stripslashes_safe()</code>:<br />
print_heading()<br />
print_heading_with_help()<br />
print_heading_block()<br />
print_simple_box()<br />
It usually doesn't matter too much for headings, because including \\, \', or \" in headings is unusual, but it does matter in print_simple_box() and therefore the advice would be to avoid using this function and to use the <code>print_simple_box_start()</code> and <code>print_simple_box_end()</code> pair.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16703Development:Slashes2006-10-07T12:07:27Z<p>Delius: </p>
<hr />
<div>The functions <code>addslashes()</code> and <code>stripslashes()</code> are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the <code>addslashes()</code> function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the <code>stripslashes()</code> function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
<br />
[[Image:stripslashes.jpg|none]]<br />
<br />
Neither <code>stripslashes()</code> nor <code>addslashes()</code> should be used when going from User Input to the Database or from the Database to Screen Output (black arrows) but <code>stripslashes()</code> should be used when displaying user input on the screen (red arrow) and <code>addslashes()</code> should be used when reinserting data in to the database that came from the database (blue arrow). These last two are rare, so the use of addslashes and stripslashes should be rare.<br />
<br />
Sometimes you may want to add slashes or remove slashes from all proprties of an object at once. Moodle provides the very convenient functions <code>addslashes_object()</code> and <code>stripslashes_recursive()</code>. The latter also works on arrays.<br />
<br />
Moodle provides a function called <code>stripslashes_safe()</code> which only strips slashes in front of single and double quotes and in front of a backslash, so \' becomes ', \" becomes ", and \\ becomes \. Any other slashes, as in C:\Moodle for example, are preserved. It was introduced because in some circumstances it may not matter if this function is applied too often. However I find this function dangerous, because it may make you think that everything is fine until one of your users wants to include a bit of code in their input for example. I would not have been able to write this paragraph (with the \' in it) if it had been passed through <code>stripslashes_safe()</code>.<br />
<br />
Some core Moodle functions use <code>stripslashes_safe()</code>:<br />
print_heading()<br />
print_heading_with_help()<br />
print_heading_block()<br />
print_simple_box()<br />
It usually doesn't matter too much for headings, because including \\, \', or \" in headings is unusual, but it does matter in print_simple_box() and therefore the advice would be to avoid using this function and to use the <code>print_simple_box_start()</code> and <code>print_simple_box_end()</code> pair.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16702Development:Slashes2006-10-07T11:59:35Z<p>Delius: Added diagram and explanations</p>
<hr />
<div>The functions addslashes() and stripslashes() are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the addslashes() function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the stripslashes() function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
[[Image:stripslashes.jpg]]<br />
<br />
Neither stripslashes() nor addslashes() should be used when going from User Input to the Database or from the Database to Screen Output (black arrows) but stripslashes() should be used when displaying user input on the screen (red arrow) or when reinserting data in to the database that came from the database (blue arrow). These last two are rare, so the use of addslashes and stripslashes should be rare.<br />
<br />
Sometimes you may want to add slashes or remove slashes from all proprties of an object at once. Moodle provides the very convenient functions <code>addslashes_object()</code> and <code>stripslashes_recursive()</code>. The latter also works on arrays.<br />
<br />
Moodle provides a function called stripslashes_safe() which only strips slashes in front of single and double quotes and in front of a backslash, so \' becomes ', \" becomes ", and \\ becomes \. Any other slashes, as in C:\Moodle for example, are preserved. It was introduced because in some circumstances it may not matter if this function is applied too often. However I find this function dangerous, because it may make you think that everything is fine until one of your users wants to include a bit of code in their input for example. I would not have been able to write this paragraph (with the \' in it) if it had been passed through stripslashes_safe().<br />
<br />
Some core Moodle functions use stripslashes_safe():<br />
print_heading()<br />
print_heading_with_help()<br />
print_heading_block()<br />
print_simple_box()<br />
It usually doesn't matter too much for headings, because including \\, \', or \" in headings is unusual, but it does matter in print_simple_box() and therefore the advice would be to avoid using this function and to use the print_simple_box_start() and print_simple_box_end() pair.</div>Deliushttps://docs.moodle.org/30/en/index.php?title=File:Stripslashes.jpg&diff=16701File:Stripslashes.jpg2006-10-07T11:39:16Z<p>Delius: Diagram showing when to use addslashes() and when to use stripslashes()</p>
<hr />
<div>Diagram showing when to use addslashes() and when to use stripslashes()</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Output_functions&diff=16700Development:Output functions2006-10-07T11:01:37Z<p>Delius: </p>
<hr />
<div>This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in an organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.<br />
<br />
By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!<br />
<br />
Of course, thess functions can be discussed, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].<br />
<br />
For each of the functions below we'll try to explain when they should be used, explaining the most important parameters supported and their meaning. Let's review them!<br />
<br />
=== p() and s() ===<br />
<br />
function s($var, $strip=false) and function p($var, $strip=false)<br />
<br />
These functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.<br />
<br />
These functions should be used to:<br />
<br />
* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.<br />
* to '''show plain (non html) text''' that has been introduced by the user (search string, quiz responses...).<br />
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters<br />
<br />
It is important not to use these functions for strings that contain html markup.<br />
<br />
The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.<br />
<br />
The key parameter for this function is:<br />
<br />
* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).<br />
<br />
=== format_text() ===<br />
<br />
function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL ) <br />
<br />
This function should be used to:<br />
<br />
* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...<br />
<br />
Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates processing to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links. Also, it includes a strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.<br />
<br />
Some interesting parameters for this function are:<br />
<br />
* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOW.<br />
<br />
* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:<br />
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true never''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for FORMAT_PLAIN, the text is never cleaned.<br />
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.<br />
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true). This is ignored by FORMAT_PLAIN for which smileys are never converted.<br />
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.<br />
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.<br />
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.<br />
<br />
=== format_string() ===<br />
<br />
function format_string ($string, $striplinks = false, $courseid=NULL )<br />
<br />
This function should be used to:<br />
<br />
* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).<br />
<br />
Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of it options nor protections'''. It simply filters the strings and return the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.<br />
<br />
Some interesting parameters for this function are:<br />
<br />
* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result test. Used when we want to show the text inside menus, page titles... (defaults to false).<br />
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.<br />
<br />
=== print_textarea() ===<br />
<br />
function print_textarea($usehtmleditor, $rows, $cols, $width, <br />
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)<br />
<br />
This function should be used to:<br />
<br />
* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.<br />
<br />
Some interesting parameters for this function are:<br />
<br />
* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.<br />
* '''rows, cols''': to be applied it the standard textarea is showed.<br />
* '''width, height''': to be applied if the HTML editor is used.<br />
* '''name''': the name of the field that will contain the text once the form was submitted.<br />
* '''value''': the initial value of the textarea.<br />
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.<br />
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.<br />
<br />
[[Category:Developer]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Slashes&diff=16699Development:Slashes2006-10-07T10:46:53Z<p>Delius: I still have to draw the diagram for this page</p>
<hr />
<div>The functions addslashes() and stripslashes() are misused often, so here is a short explanation of what they are for and when they should be used.<br />
<br />
Before entering data into a database, special symbols like single or double quotes need to be escaped by a backslash. So for example every ' needs to be converted to \' in any string that is to be stored in the database. When the string is fetched back from the database it comes back without those slashes. So if data that comes directly from the database is to be written back to the database it needs to have the slashes added to it again. This is an example where the addslashes() function should be used. <br />
<br />
Because data submitted by the user will often need to be written to the database, Moodle ensures that it automatically gets slashes added to it. So you never have to use addslashes() on data that comes from the user. If however you want to display data that was submitted by the user then you have to strip the slashes that have been added. This is an example where the stripslashes() function should be used.<br />
<br />
The whole situation can be summarized in the following diagram:<br />
<br />
(Diagram in preparation)</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Coding&diff=16698Development:Coding2006-10-07T10:35:26Z<p>Delius: /* General rules */ Added link to Developer:Output_functions</p>
<hr />
<div>Any collaborative project needs consistency and stability to stay strong.<br />
<br />
These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.<br />
<br />
==General rules==<br />
<br />
# All code files should use the .php extension.<br />
# All template files should use the .html extension.<br />
# All text files should use Unix-style text format (most text editors have this as an option).<br />
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.<br />
# All existing copyright notices must be retained. You can add your own if necessary.<br />
# Each file should include the main config.php file.<br />
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().<br />
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.<br />
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.<br />
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.<br />
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().<br />
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:<br />
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.<br />
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.<br />
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].<br />
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly. More information can be found on the page about [[Developer:Output_functions|output functions]].<br />
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].<br />
<br />
==Coding style==<br />
<br />
I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.<br />
<br />
1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.<br />
<br />
2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.<br />
<br />
GOOD: $quiz<br />
GOOD: $errorstring<br />
GOOD: $assignments (for an array of objects)<br />
GOOD: $i (but only in little loops)<br />
<br />
BAD: $Quiz<br />
BAD: $aReallyLongVariableNameWithoutAGoodReason<br />
BAD: $error_string<br />
<br />
3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.<br />
<br />
define("FORUM_MODE_FLATOLDEST", 1);<br />
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).<br />
<br />
function forum_set_display_mode($mode=0) {<br />
global $USER, $CFG;<br />
<br />
if ($mode) {<br />
$USER->mode = $mode;<br />
} else if (empty($USER->mode)) {<br />
$USER->mode = $CFG->forum_displaymode;<br />
}<br />
}<br />
<br />
5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:<br />
<br />
if ($quiz->attempts) {<br />
if ($numattempts > $quiz->attempts) {<br />
error($strtoomanyattempts, "view.php?id=$cm->id");<br />
}<br />
}<br />
<br />
6. Strings should be defined using single quotes where possible, for increased speed.<br />
<br />
$var = 'some text without any variables';<br />
$var = "with special characters like a new line \n";<br />
$var = 'a very, very long string with a '.$single.' variable in it';<br />
$var = "some $text with $many variables $within it";<br />
<br />
7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.<br />
<br />
* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.<br />
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.<br />
<br />
/**<br />
* The description should be first, with asterisks laid out exactly<br />
* like this example. If you want to refer to a another function,<br />
* do it like this: {@link clean_param()}. Then, add descriptions<br />
* for each parameter as follows.<br />
*<br />
* @param int $postid The PHP type is followed by the variable name<br />
* @param array $scale The PHP type is followed by the variable name<br />
* @param array $ratings The PHP type is followed by the variable name<br />
* @return mixed<br />
*/<br />
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {<br />
if (!$ratings) {<br />
$ratings = array(); // Initialize the empty array<br />
if ($rates = get_records("forum_ratings", "post", $postid)) {<br />
// Process each rating in turn<br />
foreach ($rates as $rate) {<br />
....etc<br />
<br />
8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:<br />
<br />
foreach ($objects as $key => $thing) {<br />
process($thing);<br />
}<br />
<br />
if ($x == $y) {<br />
$a = $b;<br />
} else if ($x == $z) {<br />
$a = $c;<br />
} else {<br />
$a = $d;<br />
}<br />
<br />
9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.<br />
<br />
BAD: $b = $a;<br />
GOOD: $b = clone($a);<br />
<br />
If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.<br />
<br />
==Database structures==<br />
<br />
# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])<br />
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:<br />
#* id - as described above<br />
#* course - the id of the course that each instance belongs to<br />
#* name - the full name of each instance of the module<br />
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).<br />
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.<br />
# Column names should be always lowercase, simple and short, following the same rules as for variable names.<br />
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)<br />
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.<br />
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.<br />
# Always define a default value for each field (and make it sensible)<br />
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.<br />
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):<br />
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.<br />
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.<br />
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated. <br />
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.<br />
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.<br />
<br />
==Security issues (and handling form and URL data)==<br />
<br />
# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from<br />
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.<br />
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Use data_submitted(), with care. Data must still be cleaned before use.<br />
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.<br />
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....<br />
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.<br />
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.<br />
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()<br />
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().<br />
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).<br />
# Do not use data from $_SERVER if you can avoid it. This has portability issues.<br />
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.<br />
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.<br />
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.<br />
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.<br />
<br />
[[Category:Developer]]<br />
<br />
[[es:Manual de Estilo de Código]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Filters&diff=16697Development:Filters2006-10-07T10:33:54Z<p>Delius: /* To create a filter */</p>
<hr />
<div>'''Please note:''' This page contains information for developers. You may prefer to read the [[Filters (administrator)| information about filters for teachers and administrators]].<br />
<br />
-----<br />
<br />
'''Filters''' allow for the for the automatic transformation of entered text into different, often more complex forms. For example the titles of [[Resources]] can automatically become hyperlinks that take you to the relevant resource, URLs pointing to [[mp3]] files can become [[Flash]] controls embedded in the webpage that let you pause and rewind the audio. The possibilities are endless and there are a number of standard filters included with Moodle and many more specialized filters contributed by the community.<br />
<br />
==To create a filter==<br />
<br />
To create a filter that removes all occurrences of the letter "x" - we'll call it "removex":<br />
<br />
# Create a new folder inside Moodle's /filter/ folder, called "removex"<br />
# Create a new PHP script file inside the folder you've just created - name it "filter.php"<br />
# Write a new PHP function in this file, called "removex_filter()" which takes two parameters - a course ID and a piece of text to be filtered - and returns the processed text.<br />
<br />
For our example the filter.php file would look like:<br />
<?php<br />
function filter_removex($courseid, $text) {<br />
return str_replace("x", "", $text);<br />
}<br />
?><br />
<br />
When trying this out, remember to make sure that you activate the filter in the [[Filters (administrator)|filters administration screen]].<br />
<br />
Also remember that text filtering functions, when activated, will be used intensively by the server, so you should optimise the filters as far as possible (cut down on database calls etc). Moodle caches the results of filtering to help with processing speed, but it's still worth being careful about your filter design.<br />
<br />
Filters are applied to all text that is printed with the [[Developer:Output functions|output functions]] format_text() or format_string(). One thing to keep in mind when designing the filter is that the function format_text() first applies other transformations (for example text_to_html() or replace_smilies()) before the strings are passed to your filter. The function format_string() on the other hand passes the string as it is.<br />
<br />
==Adding a settings screen==<br />
<br />
Moodle 1.6 added the options for filters to have their own settings screen. To do this perform the following steps:<br />
* In the same folder as the filter create a file called '''filterconfig.html'''.<br />
* For the parameters you want to be edited provide appropriate form fields (note you should not provide the actual form tag itself)<br />
* The format of the field names should be '''filter_filtername_fieldname'''; where '''filtername''' is the name of the filter (ie, the name of the folder) and '''fieldname''' the name of the field ('''filter''' is the actual word ''filter''). The field will be created as a config variable, so you can display the current value with '''$CFG->filter_filtername_fieldname. Example:<br />
<br />
<textarea type="text" name="filter_censor_badwords" cols="60" rows="10"><br />
<?php echo "$CFG->filter_censor_badwords"; ?><br />
</textarea><br />
<br />
* you will need to pay attention to setting the default value for these parameters. As filters are pluggable it is best to do it in the filter, but bear in mind that you must check the default both in the settings screen and in the filter itself as you cannot know which will be called first. Some filters with extensive lists of parameters call an external script for this purpose (see, for example, the multimedia filter)<br />
<br />
==See also==<br />
<br />
* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system<br />
* [[Filters (administrator)]]<br />
<br />
[[Category:Developer]]<br />
[[Category:Filter]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Output_functions&diff=16696Output functions2006-10-07T10:32:41Z<p>Delius: Output functions moved to Developer:Output functions: This is a page for developers</p>
<hr />
<div>#redirect [[Developer:Output functions]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Output_functions&diff=16695Development:Output functions2006-10-07T10:32:41Z<p>Delius: Output functions moved to Developer:Output functions</p>
<hr />
<div>This page tries to explain a bit how dynamic data should be sent from Moodle to the browser in a organised and standard way. Obviously it's possible to have your own output methods but, thinking that you are going to share your code (yep, this is an OpenSource project!) and in the collaborative way we try to build and maintain the system every day, it would be really better to follow the basic guidelines explained below.<br />
<br />
By using them you will be helping to have better, more secure and readable code. Spend some minutes trying to understand them, please!<br />
<br />
Of course, this functions can be discused, modified and new functions can arrive if there are some good reasons for it. Just discuss it in the [http://moodle.org/mod/forum/view.php?id=55 General developer forum] at [http://moodle.org moodle.org].<br />
<br />
For each of the functions below we'll try to explain when they should be used, commenting the most important parameters supported and their meaning. Let's review them!<br />
<br />
=== p() and s() ===<br />
<br />
function s($var, $strip=false) and function p($var, $strip=false)<br />
<br />
This functions share the same code so they will be explained together. The only difference is that s() returns the string while p() prints it directly.<br />
<br />
This functions should be used to:<br />
<br />
* print all the '''values of form fields''' like <nowiki><input></nowiki> or <nowiki><textarea></nowiki> tags.<br />
* to '''show plain (non html) text''' that have been introduced by the user (search string, quiz responses...).<br />
* in general, all the '''dynamic data, not being html''', that doesn't need to be cleaned nor processed by filters<br />
<br />
It is important not to use these functions for strings that contain html markup.<br />
<br />
The functions replace certain characters that would have special meaning in html ( <, >, ", ', and &) by html entities so that they are displayed as intended. Note that even though the value of form fields printed with p() will have these characters converted to html entities, the submitted values will contain the original characters again.<br />
<br />
The key parameter for this function is:<br />
<br />
* '''strip''': it decides if we want to strip slashes from the string or no. By default it's 'false' so no strip will be performed. We should set such parameter to 'true' only when data to be processed isn't coming from database but from http requests (forms, links...).<br />
<br />
=== format_text() ===<br />
<br />
function format_text($text, $format=FORMAT_MOODLE, $options=NULL, $courseid=NULL ) <br />
<br />
This function should be used to:<br />
<br />
* print '''any html/plain/markdown/moodle text''', needing any of the features below. Mainly used for long strings like posts, answers, glossary items...<br />
<br />
Note that this function is really '''heavy''' because it supports '''cleaning''' of dangerous contents, delegates process to enabled '''filter'''s, supports different '''formats''' of text (HTML, PLAIN, MARKDOWN, MOODLE) and performs a lot of '''automatic conversions''' like adding smilies, build links, so it's a really heavy function. Also, it includes one strong '''cache mechanism''' (DB based) that will alleviate the server from a lot of work processing the same texts time and again.<br />
<br />
Some interesting parameters for this function are:<br />
<br />
* '''format''': To tell the function about how the data has been entered. It defaults to FORMAT_MOODLE that is a cool format to process plain text because it features automatic link conversion, smilies and good conversion to html output. Other formats are FORMAT_HTML, FORMAT_PLAIN, FORMAT_MARKDOW.<br />
<br />
* '''options''': Here we can specify how we want the process to be performed. You only need to define them if they are different from the default value assumed. Main options are:<br />
**'''options->noclean''': To decide if we want to skip the clean of text, '''un-protecting us''' from attacks and other security flaws (defaults to false, so protection is enabled. You '''shouldn't set it to true never''' unless you are 200% sure that only controlled users can edit it (mainly admins). '''Never use it for general text places''' (posts...) or you will be, sooner or later, attacked! Note that this option is ignored for FORMAT_PLAIN, the text is never cleaned.<br />
**'''options->filter''': To decide if you want to allow filters to process the text (defaults to true). This is ignored by FORMAT_PLAIN for which filters are never applied.<br />
**'''options->smiley''': To decide if we want automatic conversion of smilies to images (defaults to true). This is ignored by FORMAT_PLAIN for which smileys are never converted.<br />
**'''options->para''': To decide if you want every paragraph automatically enclosed between html paragraph tags (<nowiki><p>...</p></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.<br />
**'''options->newlines''': To decide if linefeeds in text should be converted to html newlines (<nowiki><br /></nowiki>) (defaults to true). This option only applies to FORMAT_MOODLE.<br />
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.<br />
<br />
=== format_string() ===<br />
<br />
function format_string ($string, $striplinks = false, $courseid=NULL )<br />
<br />
This function should be used to:<br />
<br />
* print '''short strings (non html) that need filter processing''' (activity titles, post subjects, glossary concepts...).<br />
<br />
Please note that this function is basically one stripped version of the full format_text() function detailed above and '''it doesn't offer any of it options nor protections'''. It simply filters the strings and return the result, so we must ensure that text being processed has been properly cleaned at input time, using the proper xxx_param() functions.<br />
<br />
Some interesting parameters for this function are:<br />
<br />
* '''striplinks''': To decide if, after the text has been processed by filters, we must delete any link from the result test. Used when we want to show the text inside menus, page titles... (defaults to false).<br />
* '''courseid''': This parameter should be passed always to help filters to know how they should work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.<br />
<br />
=== print_textarea() ===<br />
<br />
function print_textarea($usehtmleditor, $rows, $cols, $width, <br />
$height, $name, $value=<nowiki>''</nowiki>, $courseid=0, $return=false)<br />
<br />
This function should be used to:<br />
<br />
* display <nowiki><textarea></nowiki> fields when we want to allow users (based in their preferences and browser capabilities) '''to use the visual HTML editor''' instead of one standard 'plain' area.<br />
<br />
Some interesting parameters for this function are:<br />
<br />
* '''usehtmleditor''': to decide if the HTML editor must be showed. The value of this parameter must be calculated by the can_use_html_editor() function.<br />
* '''rows, cols''': to be applied it the standard textarea is showed.<br />
* '''width, height''': to be applied if the HTML editor is used.<br />
* '''name''': the name of the field that will contain the text once the form was submitted.<br />
* '''value''': the initial value of the textarea.<br />
* '''courseid''': This parameter should be passed always to help the editor to know where it is work. This parameter will become less and less important Moodle was 100% of the current course using some session or global variable (it's one work in progress just now) but, for now, it's recommended to set it always in the function call.<br />
* '''return''': to decide if the generated html code must be returned to the caller (true) or printed directly (false). Defaults to false.<br />
<br />
[[Category:Developer]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Coding&diff=16694Development:Coding2006-10-07T10:29:11Z<p>Delius: /* General rules */ Added link to pages about slashes</p>
<hr />
<div>Any collaborative project needs consistency and stability to stay strong.<br />
<br />
These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.<br />
<br />
==General rules==<br />
<br />
# All code files should use the .php extension.<br />
# All template files should use the .html extension.<br />
# All text files should use Unix-style text format (most text editors have this as an option).<br />
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.<br />
# All existing copyright notices must be retained. You can add your own if necessary.<br />
# Each file should include the main config.php file.<br />
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().<br />
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.<br />
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.<br />
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.<br />
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().<br />
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:<br />
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.<br />
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.<br />
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database. Because this is so often done incorrectly, there is more explanation on this issue of adding and stripping slashes on a [[Developer:Slashes|separate page]].<br />
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly.<br />
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].<br />
<br />
==Coding style==<br />
<br />
I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.<br />
<br />
1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.<br />
<br />
2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.<br />
<br />
GOOD: $quiz<br />
GOOD: $errorstring<br />
GOOD: $assignments (for an array of objects)<br />
GOOD: $i (but only in little loops)<br />
<br />
BAD: $Quiz<br />
BAD: $aReallyLongVariableNameWithoutAGoodReason<br />
BAD: $error_string<br />
<br />
3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.<br />
<br />
define("FORUM_MODE_FLATOLDEST", 1);<br />
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).<br />
<br />
function forum_set_display_mode($mode=0) {<br />
global $USER, $CFG;<br />
<br />
if ($mode) {<br />
$USER->mode = $mode;<br />
} else if (empty($USER->mode)) {<br />
$USER->mode = $CFG->forum_displaymode;<br />
}<br />
}<br />
<br />
5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:<br />
<br />
if ($quiz->attempts) {<br />
if ($numattempts > $quiz->attempts) {<br />
error($strtoomanyattempts, "view.php?id=$cm->id");<br />
}<br />
}<br />
<br />
6. Strings should be defined using single quotes where possible, for increased speed.<br />
<br />
$var = 'some text without any variables';<br />
$var = "with special characters like a new line \n";<br />
$var = 'a very, very long string with a '.$single.' variable in it';<br />
$var = "some $text with $many variables $within it";<br />
<br />
7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.<br />
<br />
* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.<br />
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.<br />
<br />
/**<br />
* The description should be first, with asterisks laid out exactly<br />
* like this example. If you want to refer to a another function,<br />
* do it like this: {@link clean_param()}. Then, add descriptions<br />
* for each parameter as follows.<br />
*<br />
* @param int $postid The PHP type is followed by the variable name<br />
* @param array $scale The PHP type is followed by the variable name<br />
* @param array $ratings The PHP type is followed by the variable name<br />
* @return mixed<br />
*/<br />
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {<br />
if (!$ratings) {<br />
$ratings = array(); // Initialize the empty array<br />
if ($rates = get_records("forum_ratings", "post", $postid)) {<br />
// Process each rating in turn<br />
foreach ($rates as $rate) {<br />
....etc<br />
<br />
8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:<br />
<br />
foreach ($objects as $key => $thing) {<br />
process($thing);<br />
}<br />
<br />
if ($x == $y) {<br />
$a = $b;<br />
} else if ($x == $z) {<br />
$a = $c;<br />
} else {<br />
$a = $d;<br />
}<br />
<br />
9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.<br />
<br />
BAD: $b = $a;<br />
GOOD: $b = clone($a);<br />
<br />
If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.<br />
<br />
==Database structures==<br />
<br />
# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])<br />
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:<br />
#* id - as described above<br />
#* course - the id of the course that each instance belongs to<br />
#* name - the full name of each instance of the module<br />
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).<br />
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.<br />
# Column names should be always lowercase, simple and short, following the same rules as for variable names.<br />
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)<br />
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.<br />
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.<br />
# Always define a default value for each field (and make it sensible)<br />
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.<br />
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):<br />
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.<br />
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.<br />
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated. <br />
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.<br />
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.<br />
<br />
==Security issues (and handling form and URL data)==<br />
<br />
# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from<br />
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.<br />
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Use data_submitted(), with care. Data must still be cleaned before use.<br />
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.<br />
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....<br />
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.<br />
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.<br />
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()<br />
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().<br />
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).<br />
# Do not use data from $_SERVER if you can avoid it. This has portability issues.<br />
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.<br />
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.<br />
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.<br />
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.<br />
<br />
[[Category:Developer]]<br />
<br />
[[es:Manual de Estilo de Código]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=MoodleDocs:Style_guide&diff=16693MoodleDocs:Style guide2006-10-07T10:22:03Z<p>Delius: /* Screenshots */</p>
<hr />
<div>{{Help}}<br />
<br />
==Categories==<br />
<br />
*Please add at least one category to each page by typing one or more of the following at the bottom of the page: <br />
:<code><nowiki>[[Category:Teacher]]</nowiki></code>, <code><nowiki>[[Category:Administrator]]</nowiki></code>, <code><nowiki>[[Category:Developer]]</nowiki></code><br />
*[[Special:Categories&article=MoodleDocs%3AStyle_guide|Categories]] lists all Moodle Docs categories.<br />
<br />
==Screenshots==<br />
<br />
* You are encouraged to illustrate documentation with screenshots. Please use the official [http://demo.moodle.com/ Moodle demo site], or any other site or course using one of the standard themes, and ensure that the screenshot is as small as possible.<br />
* Screenshots should be GIF, JPEG or PNG format, with 72ppi resolution, and maximum width 800px.<br />
* Screenshots may be uploaded using the toolbox [[Special:Upload|Upload file]] link.<br />
* Please name screenshots descriptively to avoid confusion.<br />
* To include the screenshot in an article, use a link in the form <code><nowiki>[[Image:Screenshot.jpg]]</nowiki></code> or <code><nowiki>[[Image:Screenshot.png|alt text]]</nowiki></code>.<br />
* Please do not apply effects such as borders, watermarks or drop shadows to screenshots. This will allow others to add or replace screenshots over time and still maintain a consistent look and feel to articles.<br />
* For help on image placement and adding an image caption, please refer to the [[Wikipedia:Wikipedia:Picture_tutorial|Wikipedia Picture tutorial]].<br />
<br />
==Templates==<br />
<br />
* In MediaWiki, a template is a page which can be inserted into another page. For example, the Moodle Docs help block on this page is a template.<br />
* A template may be added to a page by typing <code><nowiki>{{Name}}</nowiki></code> for Template:''Name''.<br />
* [[Special%3AAllpages&from=&namespace=10|All pages (Template namespace)]] lists all Moodle Docs templates.<br />
* Please refer to the [http://meta.wikimedia.org/wiki/Help:Template MediaWiki Template help] for further information.<br />
<br />
[[Category:MoodleDocs|Style guide]]<br />
<br />
[[es:MoodleDocs:Guía de Estilo]]<br />
[[fr:MoodleDocs:Guide de style]]<br />
[[zh:MoodleDocs:风格指引]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Chat_activity&diff=16541Chat activity2006-10-01T14:51:12Z<p>Delius: </p>
<hr />
<div>{{Chats}}<br />
<br />
The '''Chat''' module allows participants to have a real-time synchronous discussion via the web. This is a useful way to get a different understanding of each other and the topic being discussed – the mode of using a chat room is quite different from the asynchronous forums. The Chat module contains a number of features for managing and reviewing chat discussions.<br />
<br />
== See also ==<br />
<br />
* [http://download.moodle.org/docs/using_moodle/ch4_forums.pdf Using Moodle Chapter 4: Using Forums, Chats and Dialogues]<br />
* [http://moodle.org/mod/forum/view.php?id=734 Moodle.org forum for the Chat Module]<br />
<br />
[[Category:Teacher]]<br />
[[category:Modules]]<br />
[[Category:Chat]]<br />
<br />
[[fr:Afficher un chat]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Moodle_in_education&diff=16521Moodle in education2006-10-01T09:12:41Z<p>Delius: /* Administration Block */ Moved to Administration_block</p>
<hr />
<div>==Getting started==<br />
If you are a new user and would like a list of all teacher documentation articles, please see [[:Category:Teacher]].<br />
<br />
We are assuming that your site administrator has set up Moodle, you are a user with teacher privileges and the administrator has assigned you to a new, blank course. <br />
<br />
You will need to be [[Log in | logged into]] the course using an account that has been assigned [[Teacher|teacher status]] (with editing rights) on that course to use most of the features below. We have some tips if you are having [[Can not log in | trouble logging in]].<br />
<br />
Now onto the real details. You will find the [[Course homepage|course homepage]] is broken down into [[Course sections]]. A course is created by [[Adding resources and activities|adding resources and activities]]. When writing text in Moodle you have a range of [[Formatting options]] including using [[HTML in Moodle]]<br />
<br />
The example below shows a new course set up with topic sections, edit is on and there are [[Blocks|blocks]] on the right and left sides of the topics. Resources and activities are ready to be added.<br />
[[Image:Course edit on new 2.jpg|thumb|center|500px]]<br />
<br />
==Editing a course==<br />
<br />
To add or alter activities or resources you will need to [[Turn editing on|turn editing on]]. You can do this by pressing the button at the top right of the course homepage or following the turn editing on link in the administration block. You can turn editing off again by pressing the button or the admin block link again (now renamed turn editing off)<br />
<br />
When editing is on you will see the following icons:<br />
<br />
:[[Image:Edit.gif]] - the edit icon lets you alter/update whatever resource or activity it is next to by taking you to its setup page.<br />
<br />
:[[Image:Help.gif]] - the help icon will pop-up a relevant help window.<br />
<br />
:[[Image:Open.gif]] - the open-eye icon means an item is visible to students. Clicking it will make the item invisible to participants and change the icon to the closed eye.<br />
<br />
:[[Image:Closed.gif]] - the closed-eye icon means an item is hidden from students. Clicking it will make the item visible to participants and change the icon to the open eye.<br />
<br />
:[[Image:Right.gif]] - the left icon is used to outdent course elements. There is also a right icon for indenting items.<br />
<br />
:[[Image:Move.gif]] - the move icon allows course elements to be moved up or down throughout the course.<br />
<br />
:[[Image:Movehere.gif]] - the move here icon appears when moving a course element. It appears only after you've clicked the move icon, and indicates the destination of the item you're moving.<br />
<br />
:[[Image:Delete.gif]] - the delete icon will permanently delete something from the course after you confirm a warning on a second page.<br />
<br />
:[[Image:Marker.gif]] - the marker icon allows you to make a section current.<br />
<br />
:[[Image:One.gif]] - the one icon hides all other sections of the course, showing only this one.<br />
<br />
:[[Image:All.gif]] - the all icon redisplays all sections in a course.<br />
<br />
If you are running version 1.6 or above you will see a '''Student View''' toggle button at the top right of the course homepage. This allows you to see the course almost exactly as your students will see it.<br />
<br />
==Activity modules==<br />
<br />
[[Image:Activity_dropdown.JPG|frame|right|Add an activity drop-down menu]] <br />
There are a number of robust interactive learning [[Modules (teacher)|activity modules]] that you may [[Adding_resources_and_activities | add to your course]].<br />
<br />
Communication and collaboration may take place using [[Chats]] and [[Forums]] for conversational activities and [[Choices]] to gain group feedback. Adding [[Wikis]] to your courses is an excellent way to allow students to work together on a project.<br />
<br />
Work can be submitted by students and marked by teachers using [[Assignments]] or [[Workshops]]. The [[Quizzes]] offer several options for automatic scoring. You can even integrate your Hot Potato quizzes by adding a [[Hotpot]] activity.<br />
<br />
[[Lessons]] and [[SCORM]] activities deliever content and offer ways of individualizing your presentation based upon a student's choices. Key words can be added to [[Glossaries]] by yourself or, if you allow it, your students.<br />
<br />
[[Surveys]] and [[Database module|Databases]] are also very powerful additions to any course.<br />
<br />
If all of that isn't enough for you then you can also [[Non-standard modules|add other modules]] that are not part of the official Moodle release!<br />
<br />
==Resources==<br />
<br />
[[Image:Resource_pulldown_menu.JPG|frame|left|Add a resource drop-down menu]] <br />
<br />
Moodle supports a range of different [[Resources|resource types]] that allow you to include almost any kind of digital content into your courses. These can be added by using the [[Adding_resources_and_activities | add a resource]] dropdown box when editing is turned on. <br />
<br />
A [[Text page]] is a simple page written using plain text. Text pages aren't pretty, but they're a good place to put some information or instructions. If you are after more options for your new page then you should be thinking about adding a [[Web page]] and making use of Moodle's WYSIWYG editor.<br />
<br />
Of course the resource may already exist in electronic form so you may want to [[File or website link|link to an uploaded file or external website]] or simply display the complete contents of a [[Directory|directory]] in your course files and let your users pick the file themselves. If you have an [[IMS content package]] then this can be easily added to your course.<br />
<br />
Use a [[Label|label]] to embed instructions or information in the course section.<br />
<br />
==Blocks==<br />
Each course homepage generally contains blocks on the left and right with the centre column containing the course content. Blocks may be added, hidden, deleted, and moved up, down and left/right when editing is turned on. Examples of blocks can be see in the Getting Starting image above. "Latest News", "Upcoming Events", and "Recent Activity" are blocks.<br />
<br />
A [[Blocks (teacher)|wide range of blocks]] exist that can provide additional information or functionality to the learner or teacher. There are both standard blocks that come with Moodle and many [[Non-standard blocks]] developed by Moodlers that an administrator can add to a Moodle site. <br />
<br />
<br />
<br />
==General advice==<br />
<br />
* Subscribe yourself to all of the [[forum]]s in your course so that you can keep in touch with your class activity. <br />
* Encourage all of the students to fill out their [[Edit profile|user profile]] (including photos) and read them all - this will help provide some context to their later writings and help you to respond in ways that are tailored to their own needs. <br />
* Keep notes to yourself in the private "Teacher's Forum" (under Administration). This is especially useful when team teaching. <br />
* Use the [[Logs]] link (under Administration) to get access to complete, raw logs. In there you'll see a link to a popup window that updates every sixty seconds and shows the last hour of activity. This is useful to keep open on your desktop all day so you can feel in touch with what's going on in the course. <br />
* Use the [[Recent_activity|Activity Reports]] (next to each name in the list of all people, or from any user profile page). These provide a great way to see what any particular person has been up to in the course.<br />
* Respond quickly to students. Don't leave it for later - do it right away. Not only is it easy to become overwhelmed with the volume that can be generated, but it's a crucial part of building and maintaining a community feel in your course.<br />
*Don't be afraid to experiment: feel free to poke around and change things. It's hard to break anything in a Moodle course, and even if you do it's usually easy to fix it. <br />
* Use the [[Navigation bar|navigation bar]] at the top of each page - this should help remind you where you are and prevent getting lost<br />
<br />
== See also ==<br />
*[[Teaching with Moodle]] - inspiring links<br />
*[[Teaching do's and don'ts]] - hints<br />
*[[Moodle manuals]] - A list of links to manuals and books<br />
*[[Using Moodle book]] - A real book you can reprint!<br />
*[[Teaching FAQ]] - common questions<br />
*[http://moodle.tokem.fi/mod/book/view.php?id=5116&chapterid=256 Example of a course teaching checklist], <br />
*One example of a site specific [[http://moodle.tokem.fi/mod/book/view.php?id=5116 |Teacher's Moodle Manual]], done in Moodle with the book module<br />
*[[Tips and tricks]]<br />
*[[Student FAQ]] - students have questions about technology?<br />
<br />
[[Category:Teacher]]<br />
[[es:Documentación para Profesores]]<br />
[[fr:Documentation enseignant]]<br />
[[nl:Documentatie voor leraren]]<br />
[[ru:Учителям]]<br />
[[zh:教师文档]]<br />
[[ja:教師ドキュメント]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Developer_documentation&diff=16490Development:Developer documentation2006-09-29T20:38:57Z<p>Delius: /* Resources and tools */</p>
<hr />
<div><p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>.</p><br />
<br />
==Guidelines==<br />
The following guidelines are crucial reading for anyone wanting to contribute to the Moodle code base:<br />
*[[Coding|Coding guidelines]] have to be followed by all Moodle developers<br />
*[[Moodle architecture]] spells out the basic design goals behind Moodle<br />
*[[Interface guidelines]] aim to provide a common feel to the Moodle user interface<br />
*[[CVS (developer)|Moodle CVS for developers]] explains how to work with the Moodle code in CVS<br />
*[[Unit tests]] explains how to run the unit tests, and how to write new test cases.<br />
*[[Tracker]] explains the Moodle Tracker for keeping track of bugs, issues, feature requests etc <br />
<br />
== Resources and tools ==<br />
<br />
*[[Developer FAQ]] - frequently asked questions, especially useful for newcomers to Moodle<br />
*[http://tracker.moodle.org/ Moodle tracker] - bug reports, feature requests and other tracked issues<br />
*[http://moodle.org/mod/forum/view.php?id=55 General developer forum]<br />
*[http://moodle.cvs.sourceforge.net/moodle/moodle/ CVS code] - browse the Moodle code via the web<br />
*[http://moodle.org/xref/nav.html?index.html Cross reference] - phpxref output for browsing Moodle source code<br />
*[http://phpdocs.moodle.org/ Moodle PHP doc reference] - automatically generated documentation<br />
*[http://moodle.org/course/view.php?id=5#4 Development news and discussion] section of Using Moodle course<br />
*[http://developer.yahoo.com/yui YUI documentation] - YUI is the official AJAX library in moodle.<br />
*[[Setting up Eclipse for Moodle development]] - Eclipse is a great editor to use for php development, if you can work out how to set it up.<br />
*[[Unmerged files]] - changes on the stable branch in CVS that have not been merged to HEAD<br />
<br />
==How you can contribute==<br />
<br />
The M in Moodle stands for 'Modular'. There are many different types of components that you can contribute that can be plugged into Moodle to provide additional functionality. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. The following types of plugins currently exist (in alphabetical order):<br />
*[[Modules (developer)|Activity modules]]<br />
*[[Assignment types]]<br />
*[[Authentication|Authentication methods]]<br />
*[[Blocks Howto|Blocks]]<br />
*[[Course formats]]<br />
*[[Database fields (developer)|Database fields]]<br />
*[[Database presets]]<br />
*[[Enrolment plugins (developer)|Enrolment plugins]]<br />
*[[Filters (developer)|Filters]]<br />
*[[Question_engine]]<br />
*[[Question import/export formats]]<br />
*[[Question bank|Question bank teacher docs]]<br />
*[[Question_engine#Question_types|Question types developper docs]]<br />
*[[Quiz reports]]<br />
*[[Resource types]]<br />
*[[SSO plugins]]<br />
<br />
There are also ways you can contribute that don't involve PHP programming:<br />
*[[Themes]]<br />
*[[Translation]]<br />
*[[Database Schemas|Database schemas]]<br />
<br />
You can also help a lot by<br />
*[[Tests|Testing]]<br />
*[[Tracker|Participating in the bug tracker]]<br />
<br />
==Plans for the future==<br />
Ideas for and details of planned future features of Moodle are initially discussed on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course at moodle.org. That developer discussions are intermixed with user discussions in the same forums may seem strange at first but is one of the reasons for the success of Moodle. It is important that both end-users and developers discuss the future features together.<br />
<br />
Once ideas begin to crystalize on the forums they can be summarized in this wiki, either as part of the [[Roadmap]] or in the form of [[Developer notes]]. These pages then form the basis for further discussion in the forums.<br />
*[[Roadmap]]<br />
*[[Developer notes]]<br />
*[[Student projects]]<br />
*[[Developer conference|Developer conferences]]<br />
<br />
==Documentation for core components==<br />
This section is for documentation of specific components of the existing core Moodle code. Discussion of components that are under discussion or in development can be found in the [[Developer notes]] or on the [[Roadmap]].<br />
<br />
*[[Development:Migration to Role-driven model|Migration to Role-driven model]] @ v[[1.7]]<br />
*[[UTF-8 migration|Migration to UTF-8]] @ v[[:Category:Moodle 1.6|1.6]]<br />
*[[Question engine]]<br />
*[[Quiz developer docs|Quiz module]]<br />
*[[SCORM schema|SCORM module 1.5 schema]]<br />
*[[Authentication API]]<br />
*[[Stats package]]<br />
*[[Email processing]]<br />
*[[Cookieless Sessions]]<br />
<br />
==Documentation for contributed code==<br />
Many Moodle users contribute code for the benefit of other Moodle users. This can take the form of new activity modules, blocks, themes, resource plug-ins, assignment plug-ins, question type plug-ins, question import/export formats, quiz report plug-ins, course formats, ... This code is initially posted on the forums in the [http://moodle.org/course/view.php?id=5 Using Moodle] course and then often go into the [http://cvs.sourceforge.net/viewcvs.py/moodle/contrib/ contrib area] of the Moodle [[CVS]] repository. When you have developed a new component please publish it in the [http://moodle.org/mod/data/view.php?id=6009 database of Moodle modules and plugins]. Developer documentation for these components should be listed here.<br />
<br />
==See also==<br />
*[http://security.moodle.org/ Moodle Security Centre]<br />
*[http://moodle.com/partners/ Moodle Partners] - providers of custom Moodle development services<br />
<br />
[[Category:Developer]]<br />
[[es:Documentación para Desarrolladores]]<br />
[[fr:Documentation développeur]]<br />
[[zh:开发者文档]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Developer_FAQ&diff=16489Development:Developer FAQ2006-09-29T20:38:09Z<p>Delius: Mention that datalib.php has moved to dmllib.php</p>
<hr />
<div>{{FAQ}}<br />
<br />
==Help for new coders==<br />
<br />
===Where can "newbies" to Moodle get help?===<br />
<br />
The [http://moodle.org/mod/forum/view.php?f=33 General developer forum]! Feel free to ask any question, no matter how basic or advanced. Many people ask different levels of question every day, and the community is generally welcoming and quick to respond.<br />
<br />
==Moodle's database==<br />
<br />
===Where can I see a schema for the structure of the Moodle database?===<br />
<br />
When installing Moodle, the database tables are generated and updated by various db-handling scripts located in various places. There is no canonical schema representation, although the [[Coding#Database_structures | coding guidelines for database structure]] give an outline of the general approach.<br />
<br />
The reason that the database information isn't stored in one place is because of Moodle's '''modular structure'''. Each activity module, for example, comes as a folder with script files inside. If the module needs to store information in the database, it must include scripts in a "db" subfolder which define and update the database structure.<br />
<br />
==How to get/set information when writing new Moodle code==<br />
<br />
===How do I find out the currently-logged-on user?===<br />
<br />
The global object $USER, which contains the numeric $USER->id among other things.<br />
<br />
===How do I find out the current course?===<br />
The global object $COURSE, which contains the numeric $COURSE->id<br />
<br />
===How do I insert/retrieve records in the database, without creating my own database connections?===<br />
<br />
Always use the "datalib" functions, such as insert_record() or get_record(). Since Moodle 1.7 these are found in lib/dmllib.php. Using these functions helps with database abstraction (e.g. running on either MySQL or Postgres) as well as maintaining a single database connection. Moodle uses ADODB for database abstraction.<br />
<br />
Look at [http://moodle.sourceforge.net/dhawes-phpdoc/moodlecore/_lib_datalib_php.html the documentation for datalib.php] for the list of functions and details of use.<br />
<br />
===How do I get/set configuration settings?===<br />
<br />
To get config values you would typically access the global $CFG object directly, which is automatically created by the core Moodle scripts. To set these "main" config values use set_config($name, $value). The values are stored in the Moodle "config" database table, but these functions take care of cacheing on your behalf, so you should always use these rather than fetching the records directly.<br />
<br />
There is also a second table of config settings specifically for plugins ("config_plugin"). These are not automatically loaded into the $CFG object, so to fetch these you would use get_config($plugin, $name). To set them use set_config($name, $value, $plugin).<br />
<br />
<br />
[[Category: Developer]]<br />
[[Category: FAQ]]<br />
<br />
[[es:FAQ Desarrollador]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Database_reserved_words&diff=16488Database reserved words2006-09-29T20:08:32Z<p>Delius: </p>
<hr />
<div>#REDIRECT [[Development:XMLDB reserved words]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Development:Coding&diff=16487Development:Coding2006-09-29T20:00:57Z<p>Delius: /* General rules */</p>
<hr />
<div>Any collaborative project needs consistency and stability to stay strong.<br />
<br />
These '''coding guidelines''' are to provide a goal for all Moodle code to strive to. It's true that some of the older existing code falls short in a few areas, but it will all be fixed eventually. All new code definitely must adhere to these standards as closely as possible.<br />
<br />
==General rules==<br />
<br />
# All code files should use the .php extension.<br />
# All template files should use the .html extension.<br />
# All text files should use Unix-style text format (most text editors have this as an option).<br />
# All php tags must be 'full' tags like <?php ?> ... not 'short' tags like <? ?>.<br />
# All existing copyright notices must be retained. You can add your own if necessary.<br />
# Each file should include the main config.php file.<br />
# Each file should check that the user is authenticated correctly, using require_login() and isadmin(), isteacher(), iscreator() or isstudent().<br />
# All access to databases should use the functions in ''lib/dmllib.php'' whenever possible - this allows compatibility across a wide range of databases. You should find that almost anything is possible using these functions. If you must write SQL code then make sure it is: cross-platform; restricted to specific functions within your code (usually a lib.php file); and clearly marked.<br />
# Don't create or use global variables except for the standard $CFG, $SESSION, $THEME, $SITE, $COURSE and $USER.<br />
# All variables should be initialised or at least tested for existence using isset() or empty() before they are used.<br />
# All strings should be translatable - create new texts in the "lang/en_utf8" files with concise English lowercase names and retrieve them from your code using get_string() or print_string().<br />
# All help files should be translatable - create new texts in the "lang/en_utf8/help" directory and call them using helpbutton(). If you need to update a help file:<br />
#* with a minor change, where an old translation of the file would still make sense, then it's OK to make the change but you should notify translation AT moodle DOT org.<br />
#* for a major change you should create a new file by adding an incrementing number (eg filename2.html) so that translators can easily see it's a new version of the file. Obviously the new code and the help index files should also be modified to point to the newest versions.<br />
# Incoming data from the browser (sent via GET or POST) automatically has magic_quotes applied (regardless of the PHP settings) so that you can safely insert it straight into the database. All other raw data (from files, or from databases) must be escaped with addslashes() before inserting it into the database.<br />
# VERY IMPORTANT: All texts within Moodle, especially those that have come from users, should be printed using the format_text() function. This ensures that text is filtered and cleaned correctly.<br />
# User actions should be logged using the [[Development:Logs|add_to_log()]] function. These logs are used for [[Settings#Show_activity_reports|activity reports]] and [[Logs]].<br />
<br />
==Coding style==<br />
<br />
I know it can be a little annoying to change your style if you're used to something else, but balance that annoyance against the annoyance of all the people trying later on to make sense of Moodle code with mixed styles. There are obviously many good points for and against any style that people use, but the current style just is, so please stick to it.<br />
<br />
1. Indenting should be consistently 4 spaces. Don't use tabs AT ALL.<br />
<br />
2. Variable names should always be easy-to-read, meaningful lowercase English words. If you really need more than one word then run them together, but keep them short as possible. Use plural names for arrays of objects.<br />
<br />
GOOD: $quiz<br />
GOOD: $errorstring<br />
GOOD: $assignments (for an array of objects)<br />
GOOD: $i (but only in little loops)<br />
<br />
BAD: $Quiz<br />
BAD: $aReallyLongVariableNameWithoutAGoodReason<br />
BAD: $error_string<br />
<br />
3. Constants should always be in upper case, and always start with the name of the module. They should have words separated by underscores.<br />
<br />
define("FORUM_MODE_FLATOLDEST", 1);<br />
4. Function names should be simple English lowercase words, and start with the name of the module to avoid conflicts between modules. Words should be separated by underscores. Parameters should always have sensible defaults if possible. Note there is no space between the function name and the following (brackets).<br />
<br />
function forum_set_display_mode($mode=0) {<br />
global $USER, $CFG;<br />
<br />
if ($mode) {<br />
$USER->mode = $mode;<br />
} else if (empty($USER->mode)) {<br />
$USER->mode = $CFG->forum_displaymode;<br />
}<br />
}<br />
<br />
5. Blocks must always be enclosed in curly braces (even if there is only one line). Moodle uses this style:<br />
<br />
if ($quiz->attempts) {<br />
if ($numattempts > $quiz->attempts) {<br />
error($strtoomanyattempts, "view.php?id=$cm->id");<br />
}<br />
}<br />
<br />
6. Strings should be defined using single quotes where possible, for increased speed.<br />
<br />
$var = 'some text without any variables';<br />
$var = "with special characters like a new line \n";<br />
$var = 'a very, very long string with a '.$single.' variable in it';<br />
$var = "some $text with $many variables $within it";<br />
<br />
7. Comments should be added as much as is practical, to explain the code flow and the purpose of functions and variables.<br />
<br />
* Every function (and class) should use the popular [http://www.phpdoc.org/ phpDoc format]. This allows code documentation to be generated automatically.<br />
* Inline comments should use the // style, laid out neatly so that it fits among the code and lines up with it.<br />
<br />
/**<br />
* The description should be first, with asterisks laid out exactly<br />
* like this example. If you want to refer to a another function,<br />
* do it like this: {@link clean_param()}. Then, add descriptions<br />
* for each parameter as follows.<br />
*<br />
* @param int $postid The PHP type is followed by the variable name<br />
* @param array $scale The PHP type is followed by the variable name<br />
* @param array $ratings The PHP type is followed by the variable name<br />
* @return mixed<br />
*/<br />
function forum_get_ratings_mean($postid, $scale, $ratings=NULL) {<br />
if (!$ratings) {<br />
$ratings = array(); // Initialize the empty array<br />
if ($rates = get_records("forum_ratings", "post", $postid)) {<br />
// Process each rating in turn<br />
foreach ($rates as $rate) {<br />
....etc<br />
<br />
8. Space should be used liberally - don't be afraid to spread things out a little to gain some clarity. Generally, there should be one space between brackets and normal statements, but no space between brackets and variables or functions:<br />
<br />
foreach ($objects as $key => $thing) {<br />
process($thing);<br />
}<br />
<br />
if ($x == $y) {<br />
$a = $b;<br />
} else if ($x == $z) {<br />
$a = $c;<br />
} else {<br />
$a = $d;<br />
}<br />
<br />
9. When making a COPY of an object, always use the php5 clone() function (otherwise you may end up with just a reference to the first object). Moodle will make sure this works consistently on php4 too.<br />
<br />
BAD: $b = $a;<br />
GOOD: $b = clone($a);<br />
<br />
If the thing you want to copy is not an object, but may contain objects (eg an array of objects) then use fullclone() instead.<br />
<br />
==Database structures==<br />
<br />
# Every table must have an auto-incrementing id field (INT10) as primary index. (see [[IdColumnReasons]])<br />
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:<br />
#* id - as described above<br />
#* course - the id of the course that each instance belongs to<br />
#* name - the full name of each instance of the module<br />
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).<br />
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation.<br />
# Column names should be always lowercase, simple and short, following the same rules as for variable names.<br />
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)<br />
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.<br />
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.<br />
# Always define a default value for each field (and make it sensible)<br />
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.<br />
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/colum aliases, of course):<br />
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.<br />
#* '''Use'''' the '''AS''' keyword for '''column aliases'''.<br />
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated. <br />
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.<br />
<br />
==Security issues (and handling form and URL data)==<br />
<br />
# Do not rely on 'register_globals'. Every variable must be properly initialised in every code file. It must be obvious where the variable came from<br />
# Initialise all arrays and objects, even if empty. $a = array() or $obj = new stdClass();.<br />
# Do not use the optional_variable() function (this function is now deprecated). Use the optional_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Do not use the require_variable() function (this function is now deprecated). Use the required_param() function instead. Pick the correct PARAM_XXXX value for the data type you expect.<br />
# Use data_submitted(), with care. Data must still be cleaned before use.<br />
# Do not use $_GET, $_POST or $_REQUEST. Use the appropriate required_param() or optional_param() appropriate to your need.<br />
# Do not check for an action using something like if (isset($_GET['something'])). Use, e.g., $something = optional_param( 'something',-1,PARAM_INT ) and then perform proper test for it being in its expected range of values e.g., if ($something>=0) {....<br />
# Wherever possible group all your required_param(), optional_param() and other variables initialisation at the beginning of each file to make them easy to find.<br />
# Use 'sesskey' mechanism to protect form handling routines from attack. Basic example of use: when form is generated, include <input type="hidden" name="sesskey" value="<?php echo sesskey(); ?>" />. When you process the form check with if (!confirm_sesskey()) {error('Bad Session Key');}.<br />
# All filenames must be 'cleaned' using the clean_filename() function, if this has not been done already by appropriate use of required_param() or optional_param()<br />
# Any data read from the database must have addslashes() applied to it before it can be written back. A whole object of data can be hit at once with addslashes_object().<br />
# Wherever possible, data to be stored in the database must come from POST data (from a form with method="POST") as opposed to GET data (ie, data from the URL line).<br />
# Do not use data from $_SERVER if you can avoid it. This has portability issues.<br />
# If it hasn't been done somewhere else, make sure all data written to the database has been through the clean_param() function using the appropriate PARAM_XXXX for the datatype.<br />
# If you write custom SQL code, make very sure it is correct. In particular watch out for missing quotes around values. Possible SQL 'injection' exploit.<br />
# Check all data (particularly that written to the database) in every file it is used. Do not expect or rely on it being done somewhere else.<br />
# Blocks of code to be included should contain a definite PHP structure (e.g, a class declaration, function definition(s) etc.) - straight blocks of code promote uninitialised variable usage.<br />
<br />
[[Category:Developer]]<br />
<br />
[[es:Manual de Estilo de Código]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Blogs&diff=15294Blogs2006-09-03T16:50:06Z<p>Delius: Moved section about non-Moodle bloging tools to the bottom</p>
<hr />
<div>{{Template:Blogs}}<br />
{{Moodle 1.6}}<br />
<br />
Blogs allow students, teachers and administrators to have a public web log. This online journal has various settings to control who can read them.<br />
<br />
Blogs in Moodle are user based - each user has their own Blog. Admins, teachers, and students can create Tags - Admins can create site level tags, teachers can create Course level tags, and students can create their own list of tags.<br />
<br />
When a blog entry is created, a user can select which tags they wish to associate with their new entry. - multiple tags can be selected. Users can also select who they want the blog entry to be available to - (depending on the global settings of the site.)<br />
<br />
==See also==<br />
<br />
*[http://en.wikipedia.org/wiki/Weblog Wikipedia on Blogs]<br />
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=44830 Blogs and comments] forum discussion<br />
*[[Blogs development]]<br />
<br />
==Blogs outside of Moodle==<br />
<br />
Many companies and organisations on the web provide blog sites and they are generally free. The largest company to do this is blogger which is owned by Google. There are also many Open Source web applications that can be downloaded and installed freely. The most common of these is Wordpress.<br />
<br />
*[[Elgg]]<br />
*[http://www.blogger.com Blogger.com]<br />
*[http://www.wordpress.org Wordpress]<br />
[[Category:Teacher]]<br />
[[Category:Blog]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Turn_editing_on&diff=15276Turn editing on2006-09-03T12:34:27Z<p>Delius: Reverted edit of Hedanet, changed back to last version by Rcollman</p>
<hr />
<div>==General==<br />
<br />
The '''turning editing on''' option can be found as a link in the administration block or as a button at the top right of a course homepage. This option is only available to teachers of the course who also have editing rights or to those users who are assigned site administration rights. Turn editing on allows teachers to change the appearance and functionality of the course. You can turn editing off again by pressing the button or the admin block link again (both now renamed turn editing off!)<br />
<br />
You will see these icons frequently when editing is on:<br />
<br />
:[[Image:Edit.gif]] - the edit icon lets you alter/update whatever resource or activity it is next to.<br />
<br />
:[[Image:Help.gif]] - the help icon will popup a relevant help window<br />
<br />
==Blocks==<br />
<br />
Existing blocks can be moved up, down or sent to the right or left column of the course. They can also be set to visible or hidden. They can be removed completely by pressing the X icon.<br />
<br />
You will see these icons when editing blocks:<br />
<br />
:[[Image:Block open.gif]] - the block is visible. Clicking the eye will hide the block from students<br />
<br />
:[[Image:Block closed.gif]] - the block is hidden. Clicking the eye will show the block to students<br />
<br />
:[[Image:Block delete.gif]] - clicking this icon will remove the block from the course<br />
<br />
:[[Image:Block up.gif]] - this icon will move the block upwards<br />
<br />
:[[Image:Block down.gif]] - this icon will move the block down<br />
<br />
:[[Image:Block left.gif]] - this icon will move the block to the bottom of the left column<br />
<br />
:[[Image:Block right.gif]] - this icon will move the block to the bottom of the right icon<br />
<br />
==Sections==<br />
Topics or weeks are the most common types of section formats. The section description that appears to student can be edited with the [[Image:Edit.gif]] edit icon. <br />
<br />
Sections can be moved up or down to change the order in which the course is dispayed. Sections can also be hidden from, or made visible to, learners. If the course is topic based then a topic can be set as current (or indeed the current status can be removed).<br />
<br />
:[[Image:Open.gif]] - the open-eye icon means an item is visible to students. It will close when you click on it<br />
<br />
:[[Image:Closed.gif]] - the closed-eye icon means an item is hidden from students. It will open when you click on it.<br />
<br />
:[[Image:Marker.gif]] - the marker icon allows you to make a section current<br />
<br />
The following icons are visible when editing is both on and off<br />
<br />
:[[Image:One.gif]] - This icon is used to show only the selected section<br />
<br />
:[[Image:All.gif]] - This icon is used to show all sections in a course<br />
==Activities and Resources==<br />
<br />
Course resources and activities may be added, removed, indented, moved, updated, deleted, hidden, shown or assigned to groups. The teacher can edit individual activities and resources in a section by clicking on their individual icons.<br />
<br />
:[[Image:Right.gif]] - the right icon is used to indent course elements (there is also a left icon)<br />
<br />
:[[Image:Move.gif]] - the move icon allows course elements to be placed anywhere<br />
<br />
:[[Image:Movehere.gif]] - the move here icon appears when moving a course element <br />
<br />
:[[Image:Delete.gif]] - the delete icon will permentantly delete something from the course<br />
<br />
==See Also==<br />
[[Teacher documentation]]<br />
[[Category: Teacher]]<br />
<br />
[[fr:Activer le mode édition]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Installing_AMP&diff=14984Installing AMP2006-08-27T14:39:16Z<p>Delius: /* Windows */ a bit more detail on how to start the service</p>
<hr />
<div>Moodle is written in a scripting language called [[PHP]] and stores most of its data in a database. The recommended database is [[MySQL]]. Before installing Moodle you must have a working PHP installation and a working database to turn your computer into a functional web server platform. These packages can be tricky to set up for average computer users, so this page has been written to try to make this process as simple as possible for different platforms:<br />
<br />
== Hosting Service ==<br />
<br />
Unfortunately hosting services vary quite a lot in the way they work. Some will even install Moodle for you.<br />
<br />
Most will offer a web-based control panel to control your site, create databases and set up cron. Some may also offer terminal access via ssh, so that you can use the command shell to do things.<br />
<br />
You should work your way through the [[Installing Moodle|Installation guide]] and take each step at a time. Ask your hosting provider if you get stuck.<br />
<br />
== Mac OS X ==<br />
<br />
The easiest way to do this is use the [[Apache]] server that Apple provides, and add PHP and MySQL using Marc Liyanage's packages. Both of the pages below come with good instructions that we won't duplicate here:<br />
<br />
* '''PHP''': Download from here: http://www.entropy.ch/software/macosx/php/<br />
* '''MySQL''': Download here: http://www.entropy.ch/software/macosx/mysql/<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
Go here for a [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client]] (not server) Mac.<br />
<br />
== Red Hat Linux ==<br />
<br />
You should install all available RPM packages for Apache, PHP and MySQL. One package that people frequently forget is the php-mysql package which is necessary for PHP to talk to MySQL.<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
A more detailed walkthrough is here: [[RedHat Linux installation]]<br />
<br />
== Windows ==<br />
<br />
For those who want to install Moodle '''for the first time''' on a localhost (a stand alone computer, a very useful tool even if you have a web based Moodle Server), here is a step by step, that works on a Window XP computer:<br />
#In the [http://download.moodle.org/?lang=en Download section], find the second group called "Complete Install Packages (Moodle+Apache+MySQL+PHP)" and choose the version you would like. Click on the download link on the far right, which will download a large zip file.<br />
#Unzip the downloaded file at c: and keep the path structure for all the files. <br />
#Rename the just created c:\moodle to c:\xampplite .<br />
#The following steps assume that the web server will be able to use port 80 on your computer. This might be a problem if you are running Skype which also likes to use this port as a default. Therefore you should quit Skype before continuing with this installation. Later, when the apache web server is running you can restart Skype which will then automatically use another available port.<br />
#In Windows Explorer click on c:\xampplite\apache_start to start the Apache web server. This opens a new window that you should leave open.<br />
#In Windows Explorer click on c:\xampplite\mysql_start to start the MySQL database server. This opens yet another new window that you should leave open.<br />
#In your favorite Web browser, go to address bar and type "localhost" and press enter or go.<br />
#This will start the Moodle Install process, which the [[Installing Moodle]] MoodleDoc page and [[Installing_Moodle#Go_to_the_admin_page_to_continue_configuration]] section describes in a little bit more detail. This can take some time for a new user. '''Don't panic''', you can change things later and the install process will tell you what you absolutely have to fill in or correct.<br />
<br />
In order to make starting Moodle more convenient in the future you could install the web server and database server as Windows services that are started automatically when you start Windows. To do this you have to run the program c:/xampplite/service.exe. To do this go to Start -> Run... and type the command "c:/xampplite/service.exe -install" into the Open: field. Then click OK.<br />
<br />
Instead of using this package you can also install XAMPP and Moodle separately as explained on the page [[Windows_installation_using_XAMPP]]. <br />
<br />
As an alternative to the above package you could use a package like EasyPHP that bundles all the software you need into a single Windows application. Note that the EasyPHP 1.8 uses older versions of the software that are too old for Moodle 1.6. Also many menus for EasyPHP are still in French. EasyPHP may be a good option again once its version 2.0 is released.<br />
<br />
Here you can find steps for an [[IIS]]: [[Windows installation]] for XAMPP or Windows 2003 .<br />
<br />
==Testing PHP==<br />
Once you have installed your web server and PHP you should be able to create a file (for example phpinfo.php in the document root) with the following in it:<br />
<br />
<?phpinfo()?><br />
<br />
You should be able to open this file in a web browser by going to to the URL '''localhost/phpinfo''' and see a web page that has PHP status information in it such as [[phpinfo|this]].<br />
<br />
==See also==<br />
<br />
*[[Installing Moodle]]<br />
*[[Installation FAQ]]<br />
*[[Upgrading Moodle]]<br />
*[[Debian GNU/Linux installation]]<br />
<br />
[[Category:Core]]<br />
[[Category:Administrator]]<br />
[[Category:Installation]]<br />
<br />
[[es:Instalación AMP]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Installing_AMP&diff=14976Installing AMP2006-08-27T14:13:38Z<p>Delius: Simplified the instructions a bit and added warning about Skype</p>
<hr />
<div>Moodle is written in a scripting language called [[PHP]] and stores most of its data in a database. The recommended database is [[MySQL]]. Before installing Moodle you must have a working PHP installation and a working database to turn your computer into a functional web server platform. These packages can be tricky to set up for average computer users, so this page has been written to try to make this process as simple as possible for different platforms:<br />
<br />
== Hosting Service ==<br />
<br />
Unfortunately hosting services vary quite a lot in the way they work. Some will even install Moodle for you.<br />
<br />
Most will offer a web-based control panel to control your site, create databases and set up cron. Some may also offer terminal access via ssh, so that you can use the command shell to do things.<br />
<br />
You should work your way through the [[Installing Moodle|Installation guide]] and take each step at a time. Ask your hosting provider if you get stuck.<br />
<br />
== Mac OS X ==<br />
<br />
The easiest way to do this is use the [[Apache]] server that Apple provides, and add PHP and MySQL using Marc Liyanage's packages. Both of the pages below come with good instructions that we won't duplicate here:<br />
<br />
* '''PHP''': Download from here: http://www.entropy.ch/software/macosx/php/<br />
* '''MySQL''': Download here: http://www.entropy.ch/software/macosx/mysql/<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
Go here for a [[Step-by-step Guide for Installing Moodle on Mac OS X 10.4 Client]] (not server) Mac.<br />
<br />
== Red Hat Linux ==<br />
<br />
You should install all available RPM packages for Apache, PHP and MySQL. One package that people frequently forget is the php-mysql package which is necessary for PHP to talk to MySQL.<br />
<br />
Once these are installed the standard [[Installing Moodle|Installation guide]] should be fairly straightforward.<br />
<br />
A more detailed walkthrough is here: [[RedHat Linux installation]]<br />
<br />
== Windows ==<br />
<br />
For those who want to install Moodle '''for the first time''' on a localhost (a stand alone computer, a very useful tool even if you have a web based Moodle Server), here is a step by step, that works on a Window XP computer:<br />
#In the [http://download.moodle.org/?lang=en Download section], find the second group called "Complete Install Packages (Moodle+Apache+MySQL+PHP)" and choose the version you would like. Click on the download link on the far right, which will download a large zip file.<br />
#Unzip the downloaded file at c: and keep the path structure for all the files. <br />
#Rename the just created c:\moodle to c:\xampplite .<br />
#The following steps assume that the web server will be able to use port 80 on your computer. This might be a problem if you are running Skype which also likes to use this port as a default. Therefore you should quit Skype before continuing with this installation. Later, when the apache web server is running you can restart Skype which will then automatically use another available port.<br />
#In Windows Explorer click on c:\xampplite\apache_start to start the Apache web server. This opens a new window that you should leave open.<br />
#In Windows Explorer click on c:\xampplite\mysql_start to start the MySQL database server. This opens yet another new window that you should leave open.<br />
#In your favorite Web browser, go to address bar and type "localhost" and press enter or go.<br />
#This will start the Moodle Install process, which the [[Installing Moodle]] MoodleDoc page and [[Installing_Moodle#Go_to_the_admin_page_to_continue_configuration]] section describes in a little bit more detail. This can take some time for a new user. '''Don't panic''', you can change things later and the install process will tell you what you absolutely have to fill in or correct.<br />
<br />
In order to make starting Moodle more convenient in the future you could install the web server and database server as Windows services that are started automatically when you start Windows. To do this simply run the program c:\xampplite\service.exe<br />
<br />
As an alternative to the above package you could use a package like EasyPHP that bundles all the software you need into a single Windows application. Note that the EasyPHP 1.8 uses older versions of the software that are too old for Moodle 1.6. Also many menus for EasyPHP are still in French. EasyPHP may be a good option again once its version 2.0 is released.<br />
<br />
See Also for Windows:<br />
<br />
https://docs.moodle.org/en/Windows_installation_using_XAMPP<br />
<br />
Here you can find steps for an [[IIS]]: [[Windows installation]] for XAMPP or Windows 2003 .<br />
<br />
==Testing PHP==<br />
Once you have installed your web server and PHP you should be able to create a file (for example phpinfo.php in the document root) with the following in it:<br />
<br />
<?phpinfo()?><br />
<br />
You should be able to open this file in a web browser by going to to the URL '''localhost/phpinfo''' and see a web page that has PHP status information in it such as [[phpinfo|this]].<br />
<br />
==See also==<br />
<br />
*[[Installing Moodle]]<br />
*[[Installation FAQ]]<br />
*[[Upgrading Moodle]]<br />
*[[Debian GNU/Linux installation]]<br />
<br />
[[Category:Core]]<br />
[[Category:Administrator]]<br />
[[Category:Installation]]<br />
<br />
[[es:Instalación AMP]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Administrator_documentation&diff=14963Administrator documentation2006-08-27T12:59:56Z<p>Delius: Removed "Planning Installation" section because all that information is in the "Installation" section</p>
<hr />
<div>The purpose of this page is to list useful links by general topics for administrators.<br />
<br />
== Installation ==<br />
<br />
*[[Installing Moodle]]<br />
*[[Installing AMP|Installing Apache, MySQL and PHP]]<br />
* [[Installation Quickstart]]<br />
*[[Installation FAQ]]<br />
*[[Upgrading|Upgrading Moodle]]<br />
<br />
==Security and performance==<br />
<br />
*[[Security]]<br />
*[[Performance]]<br />
<br />
== Configuration ==<br />
<br />
*[[Variables]]<br />
*[[Site settings]]<br />
*[[Themes]]<br />
*[[Language]]<br />
*[[Modules (administrator)|Modules]]<br />
*[[Blocks (administrator)|Blocks]]<br />
*[[Filters (administrator)|Filters]]<br />
*[[Backup (administrator)|Backup]]<br />
*[[Editor settings]]<br />
*[[Calendar (administrator)|Calendar]]<br />
*[[Maintenance mode]]<br />
<br />
==Users==<br />
<br />
*[[Authentication]]<br />
*[[Edit user accounts]]<br />
*[[Edit profile|Add a new user]]<br />
*[[Flat file|Upload users]]<br />
*[[Enrolment plugins]]<br />
*[[Courses (administrator)|Enrol students]]<br />
*[[Courses (administrator)|Assign teachers]]<br />
*[[Assign creators]]<br />
*[[Assign admins]]<br />
<br />
==Other==<br />
<br />
*[[Courses (administrator)|Courses]]<br />
**[[Course formats|Course formats]]<br />
*[[Logs]]<br />
*[[Site files]]<br />
*[[Moodle database|Database]]<br />
*[[Environment]]<br />
<br />
==See also==<br />
<br />
*[[CVS (administrator)|CVS documentation]]<br />
*[[Email processing]]<br />
*[[Search engine optimization]]<br />
*[[Messaging]]<br />
*[[Migration]]<br />
*[[Metacourses]]<br />
*[[Block layout]]<br />
*[[Backup FAQ]]<br />
*[[Administration FAQ]]<br />
*[[Administrator do's and don'ts]]<br />
*[http://download.moodle.org/docs/using_moodle/ch16_server_admin.pdf Using Moodle Chapter 16: Moodle Administration]<br />
<br />
[[Category: Administrator]]<br />
[[es:Documentación para Administradores]]<br />
[[fr:Documentation administrateur]]<br />
[[nl:Documentatie voor beheerders]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Environment&diff=11812Environment2006-06-11T17:44:43Z<p>Delius: /* 1.6 */ added warning about php 5.0.6</p>
<hr />
<div>This setting allows administrators compare their server with the minimum requirements for hosting a particular version of moodle.<br />
<br />
==1.5.3==<br />
<br />
*MySQL version - 3.23 or later is required<br />
*PHP version - 4.1.0 or later is required <br />
*The php_extension mbstring is recommended to be installed/enabled<br />
<br />
<br />
==1.6==<br />
<br />
*MySQL version 4.1.12 or later for sites that are exclusively [http://czyborra.com/charsets/iso8859.html Latin-1], 4.1.16 if you have other languages<br />
*PHP version 4.3.0 or later is required (but don't use versions 5.0.0 to 5.0.6 which were buggy)<br />
*The php_extension iconv is recommended to be installed/enabled<br />
*The php_extension mbstring is recommended to be installed/enabled<br />
<br />
<br />
[[Category:Administrator]]<br />
<br />
[[fr:Environnement]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Question_bank&diff=9600Question bank2006-05-14T13:33:09Z<p>Delius: /* Preview, Edit, Delete, and Move */</p>
<hr />
<div>{{Questions}}<br />
{{Moodle 1.6}}<br />
This allows you to create, preview, and edit questions in the course question bank. These questions can then be used in any supported course activity such as [[Quizzes]]. <br />
<br />
The page has tabs that allow you to edit questions, [[Question categories|categories]], [[Import questions|import questions]] and [[Export questions|export questions]].<br />
<br />
==Select a category==<br />
Questions are organised into categories. Initially each course has only one category called "Default". It is good practice to create more categories to organize your questions. You can create a hierarchy of categories because you can create subcategories inside parent categories. To add or edit categories click on the "[[Question categories|Categories]]" tab.<br />
<br />
The question editing screen shows the questions from the currently selected category. You choose this category from the '''Category:''' drop-down menu. Using the tick box below that menu you determine whether to also show the questions from all subcategories.<br />
<br />
==Add a new question==<br />
#From the '''Category:''' drop-down menu, select a category you want to add a question to.<br />
#The area below the category will then display the question creation block.<br />
#Select the question type you want to create from the '''Create new question''' drop-down menu.<br />
#Fill in the form for the question type you are creating. <br />
#Click Save Changes at the bottom of the form. <br />
Each [[Question types|question type]] has its own form and has its own options.<br />
<br />
==Preview, Edit, Delete, and Move==<br />
The first column in the list of questions contains a number of icons and a selection box.<br />
<br />
Clicking on the '''Preview''' icon will open a preview window in which you can test the question. The '''Edit''' icon allows you to edit the question via the same form that you used to create it. The '''Delete''' icon deletes the question, provided it is not already in use in some activity. The selection box allows you to select a subset of questions that you can then move to another category using the controls below the list of questions.<br />
<br />
[[Category:Teacher]]<br />
[[Category:Quiz]]<br />
<br />
[[es:Preguntas]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=Template:Questions&diff=9599Template:Questions2006-05-14T13:27:43Z<p>Delius: Renamed to Question bank</p>
<hr />
<div><div class="sideblock right" style="width: 12em;"><br />
<div class="header">[[Question bank]]</div><br />
<div class="content"><br />
* [[Question categories]]<br />
* [[Question types]]<br />
* [[Import questions]]<br />
* [[Export questions]]<br />
</div><br />
</div></div>Deliushttps://docs.moodle.org/30/en/index.php?title=Questions&diff=9598Questions2006-05-14T13:26:14Z<p>Delius: </p>
<hr />
<div>#redirect [[Question bank]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=mod/quiz/question&diff=9597mod/quiz/question2006-05-14T13:25:36Z<p>Delius: </p>
<hr />
<div>#redirect [[Question bank]]</div>Deliushttps://docs.moodle.org/30/en/index.php?title=question/edit&diff=9596question/edit2006-05-14T13:23:55Z<p>Delius: </p>
<hr />
<div>#redirect [[Question bank]]</div>Delius