MoodleDocs - User contributions [en]

File:sites-deployment.png

2021-09-20T18:03:00Z

Mudrd8mz:

asdfasd

User:Chris collman/handyformats

2021-08-09T12:58:48Z

Mudrd8mz: MDLSITE-6551 Fix table class

This page is for handy formats I use in MoodleDocs. Either I need a place to put links to what I think are successful formats and/or put examples here. In Wikimedia I use a subpage to format my library books. In MoodleDocs I want

==A table==

{| style="width:75%; height:200px" border="1"
|-
| abc || def || ghi
|- style="height:100px"
| jkl || style="width:200px" |mno || pqr
|-
| stu || vwx || yz
|}
==A nice table==

{| class="wikitable"
|-
!What it looks like
!What you type
|-
| A table:

{| class="wikitable"
|-
! header 1
! header 2
! header 3
|-
| row 1, cell 1
| row 1, cell 2
| row 1, cell 3
|-
| row 2, cell 1
| row 2, cell 2
| row 2, cell 3
|}

| <pre><nowiki>A table:

{| class="wikitable"
|-
! header 1
! header 2
! header 3
|-
| row 1, cell 1
| row 1, cell 2
| row 1, cell 3
|-
| row 2, cell 1
| row 2, cell 2
| row 2, cell 3
|}
</nowiki></pre>
|}

Note, the class="wikitable" is our local hack for Moodledocs. You can leave it out to get a table without borders.

==A table with picture==

{| border="1" cellpadding="2" cellspacing="0"
!width="30"|Icon
!width="100"|Effect
!width="30"|Icon
!width="100"|Effect
!width="30"|Icon
!width="100"|Effect
!width="30"|Icon
!width="100"|Effect
|-
|[[Image:Edit.gif]]|| Edit text ||[[Image:Open.gif]] || Open ||[[Image:Delete.gif]] || Delete ||[[Image:Move.gif]] ||Move
|-
||[[Image:All.gif]] ||See all topics||[[Image:Closed.gif]] ||Close||[[Image:Right.gif]] || Indent ||[[Image:Movehere.gif]] || Move here
|-
||[[Image:One.gif]] || See one topic||[[Image:Help.gif]] ||Help || || ||[[Image:Marker.gif]] ||Make Current
|}
<br>

==Picture formats==
frame
[[Image:Course_section_formats_1.JPG|frame|left|format frame, left, this label]]
<nowiki>[[Image:Course_section_formats_1.JPG|frame|left|format frame, left, this label]]</nowiki>
thumb example resized
[[Image:Course_section_formats_1.JPG|thumb|100px|center|format thumb, 100px, center, this label]]
<nowiki>[[Image:Course_section_formats_1.JPG|thumb|100px|center|format thumb, 100px, center, this label]]</nowiki>

== Modules and plugins ==
==See also==
*[Place http address for M&P entry here Name of Entry here] is a Modules and plugins database page that has downloads and more information.
*Discussions: [Place http address for moodle forum or forum thread]
**Please create or find a discussion topic in the <nowiki>[http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]</nowiki>
**The contributor also maintains a Moodle site that contains one or more [Place http address forums using and supporting xxx], outside of Moodle.org .
*Additional documentation
**[Place http address outside page Moodle] (outside of Moodle.org)
* [Place http address for M&P download put name here] for Moodle 2.0

==Forgotten templates ==
*Note format <br>
<nowiki><p class="note">'''Note:''' Moodle 2.0 has a new HTML editor. For details of the HTML editor in Moodle prior to 2.0, see [[HTML editor]].</p></nowiki>

* Update template <br>
<nowiki>{{Update}}</nowiki>

*Gallery format

<nowiki><gallery></nowiki> <br>
<nowiki>Image:Moodle.logo</nowiki><br>
<nowiki>Image:Moodle.logo|This is the a Moodle logo</nowiki><br>
<nowiki></gallery></nowiki><br>

* Gallery - fancy <br>
<nowiki><gallery caption="Possible screenshots" widths="225px" heights="120px" perrow="3"></nowiki>

==Other wiki codes==
<strike>Strikeout</strike> can be achieved by <nowiki><strike>Strikeout </strike></nowiki>. I find this useful as a tool for visually marking text to be moved or changed.

* <nowiki>#redirect [[Adding a content page]]</nowiki>
*<u>underline</u> -- No! No! No! underline is an evil abomination on the web, for anything other than links. People expect online text with an underline t be click-able. If you want to emphasise something, use bold or italic.--[[User:Tim Hunt|Tim Hunt]] 20:15, 9 December 2010 (UTC) -- Sorry for the interruption.
:Evil abomination for all those who color blind and bald headed? Point noted and taken. However, I saw "Moodle '''IS''' an online.." and all I could think of was "Moodle Information Systems" and my brain froze :) Interrupt any time.--[[User:chris collman|chris collman]] 17:32, 10 December 2010 (UTC)

==Wiki TOC codes==

* <nowiki>__TOC__</nowiki> forces placement of Table of Contents at this spot
* <nowiki>{{TOCright}}</nowiki> interesting, sort of in the template postion.
* <nowiki>[[#toc|Top]]</nowiki> - Links back to Table of Contents, says "Top"
*<nowiki>__FORCETOC__</nowiki> = for less than 4 entries to create toc
*<nowiki>__NOTOC__</nowiki>

==Note to self==
Template for update section as a special page?

<nowiki>{{Update_section}}</nowiki>

These templates work

<nowiki>{{stub}}</nowiki> Listed on special pages

<nowiki>{{Update}}</nowiki> Not listed on special pages

New features

2021-07-14T14:44:33Z

Mudrd8mz: New card-deck based layout

{{About Moodle}}
Read on for an overview of the key features and improvements in Moodle 3.11, or watch our [https://www.youtube.com/playlist?list=PLxcO_MFWQBDdG1jK_Eu_D4GC-AOGBEXh6 YouTube playlist of 3.11 New features].

For role-specific information, see [[New for teachers]], [[New for students]] and [[New for administrators]].

The list of major features and improvements can be found in the [[:dev:Moodle 3.11 release notes|Moodle 3.11 release notes]].
__NOTOC__
===Student activity completion (MUA)===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:ActivityCompletion311.png|class=img-fluid]]
<h4 class="card-title">
Improved learner experience
</h4>
<p class="card-text">
Activity dates and [[Activity completion]] conditions may be shown on the course page.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:311CompletionWithinActivity.png|class=img-fluid]]
<h4 class="card-title">
Dates and completion conditions within activities
</h4>
<p class="card-text">
Activity dates and [[Activity completion]] conditions are shown at the top of the activity page.
</p>
</div>
</div>

</div>
<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:StudentManualCompletion.png|class=img-fluid]]
<h4 class="card-title">
Manual completion
</h4>
<p class="card-text">
Students can mark an activity as complete from within the activity itself.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:TeacherCompletionSettings.png|class=img-fluid]]
<h4 class="card-title">
New display settings
</h4>
<p class="card-text">
New settings allow teachers to hide or show activity dates and completion conditions on the course page.
</p>
</div>
</div>

</div>

===Accessibility toolkit===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:BrickfieldAdmin1.png|class=img-fluid]]
<h4 class="card-title">
Free starter toolkit
</h4>
<p class="card-text">
An [[Accessibility toolkit]] (from Brickfield Education Labs) identifies course accessibility issues.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:AccessiblityBlock.png|class=img-fluid]]
<h4 class="card-title">
Course accessibility review
</h4>
<p class="card-text">
Course content is analysed so teachers can identify and fix accessibility errors.
</p>
</div>
</div>

</div>
<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:BrickfieldTeacher.png|class=img-fluid]]
<h4 class="card-title">
Heatmap of errors
</h4>
<p class="card-text">
A heatmap offers a coloured and contextual view of the areas of concern.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:SummaryReport.png|class=img-fluid]]
<h4 class="card-title">
Range of reports and graphs
</h4>
<p class="card-text">
Errors can be viewed in graphic form, or as a list with a downloadable report.
</p>
</div>
</div>
</div>

===H5P and content bank===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:DisableH5Pcontent.png|class=img-fluid]]
<h4 class="card-title">
Disable selected H5P content types
</h4>
<p class="card-text">
Admins can disable selected [[H5P|H5P content types]] from the admin settings.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:MakeUnlisted.png|class=img-fluid]]
<h4 class="card-title">
Mark content as unlisted
</h4>
<p class="card-text">
Teachers can hide content in the [[Content bank|content bank]] by marking it as unlisted.
</p>
</div>
</div>

</div>
<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:LinkedContent.png|class=img-fluid]]
<h4 class="card-title">
See which content is linked
</h4>
<p class="card-text">
A new column in the [[Content bank|content bank]] displays the number of times an item is linked.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:DeleteAlert.png|class=img-fluid]]
<h4 class="card-title">
Alert when deleting linked content
</h4>
<p class="card-text">
An alert is displayed when linked content is about to be deleted, explaining what will happen
</p>
</div>
</div>
</div>

===Quiz and question types===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:QuizOverridePassGrade.png|class=img-fluid]]
<h4 class="card-title">
View overrides and pass grades
</h4>
<p class="card-text">
Teachers can view overrides and students can view pass grades directly on the Quiz page.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:RetainedQuestionSettings.png|class=img-fluid]]
<h4 class="card-title">
Preferred question settings retained
</h4>
<p class="card-text">
Changes from the default settings of a question type are retained for the next time a teacher creates a question.
</p>
</div>
</div>

</div>
<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:QuizMinMaxStudent.png|class=img-fluid]]
<h4 class="card-title">
Essay question word limits
</h4>
<p class="card-text">
A minimum and maximum word limit can be specified for [[Essay question type|Essay questions]].
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:PlagiarismSupport.png|class=img-fluid]]
<h4 class="card-title">
Essay plagiarism support
</h4>
<p class="card-text">
If a plagiarism checker is installed, it now supports the [[Essay question type]].
</p>
</div>
</div>
</div>

===Badges===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:ManageBackPacks.png|class=img-fluid]]
<h4 class="card-title">
Better backpack management
</h4>
<p class="card-text">
Admins can set the order in which [[Backpacks|backpacks]] are listed for users.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:BadgesAPI.png|class=img-fluid]]
<h4 class="card-title">
Open Badges v 2.1 compliant
</h4>
<p class="card-text">
Moodle 3.11 is Open Badges v 2.1 compliant and a new [[OAuth 2 Open Badges service]] enables users to connect to their OB v 2.1 compliant backpack without having to enter their credentials into Moodle.
</p>
</div>
</div>
</div>

===User profile fields===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:SocialField.png|class=img-fluid]]
<h4 class="card-title">
New Social profile field
</h4>
<p class="card-text">
A new [[User profile fields#Overview| Social profile field]] replaces the hard-coded fields in the user profile.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:UserProfileUserIdentity.png|class=img-fluid]]
<h4 class="card-title">
Custom profile fields selectable in Show user identity
</h4>
<p class="card-text">
Custom profile fields may be selected in User polices > Show user identity so they display in participant lists.
</p>
</div>
</div>
</div>

===Other features and improvements===

<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:PlayRate.png|class=img-fluid]]
<h4 class="card-title">
Control audio / video playback rates
</h4>
<p class="card-text">
Students can control the speed at which [[Audio]] and [[Video]] files will play.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:ActivityCompletionreport.png|class=img-fluid]]
<h4 class="card-title">
Improved activity completion report
</h4>
<p class="card-text">
The activity completion report may be filtered by activity and activity order.
</p>
</div>
</div>

</div>
<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:SearchLangPacks.png|class=img-fluid]]
<h4 class="card-title">
Search language packs
</h4>
<p class="card-text">
The list of languages may be searched when installing new [[Language packs]].
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:Poppler.png|class=img-fluid]]
<h4 class="card-title">
New PDF to PNG converter
</h4>
<p class="card-text">
For assignment submission annotations, a new converter, Poppler is available instead of Ghostscript.
</p>
</div>
</div>

</div>
<div class="card-deck mt-3">

<div class="card">
<div class="card-body">
[[File:SectionNameLinks.png|class=img-fluid]]
<h4 class="card-title">
Section links block
</h4>
<p class="card-text">
Titles may now be displayed in the Section links block.
</p>
</div>
</div>

<div class="card">
<div class="card-body">
[[File:OverridePermissions.png|class=img-fluid]]
<h4 class="card-title">
Restore/import role permissions
</h4>
<p class="card-text">
Enable or disable role permission overrides when restoring or importing a course.
</p>
</div>
</div>
</div>

[[Category:New features]]

[[de:Neue Funktionalitäten]]
[[es:Nuevas características de Moodle 3.11]]
[[fr:Nouveautés de Moodle 3.11]]

Course contents block

2021-07-14T13:24:46Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

'''Course contents block''' produces a table of contents for the course - ie a list of all visible topics/weeks in your course. Clicking at one of these links will display that particular section (topic or week).

If the section has its name defined, the block uses it as the title for that section.

If the section name is not defined but there is the section summary (description) available, the block automatically extracts a suitable title from that summary. If you start summary with a heading (H1, H2, H3, etc), it will use such heading text. If your summary starts with a bold text, it will be used as a section title. If the summary consists of several paragraphs, the first one will be used. Technically spoken, the plain text content of the first non-empty HTML DOM node from the section summary is used as the summary title.

If the summary is empty, a customizable text "Unit X" (where X is the number) is displayed.

You can combine this feature with the multi-language filter to generate course contents in the user's language.

The block was written and is currently maintained by [[User:David Mudrak|David Mudrak]]

[[Image:course-contents-block-screenshot.png|thumb|The topic title is automatically extracted from the section summary|400px|left]]
<br clear="both" />

==Installation==

There is a public source code repository for the block at [https://github.com/mudrd8mz/moodle-block_course_contents github.com]. You can either clone that repository or just download the latest package there. Follow the instructions provided by Github or see [[Git for Administrators]] for details. This may be what you want:

# cd /var/www/moodlesite/htdocs/blocks
# git clone git://github.com/mudrd8mz/moodle-block_course_contents.git course_contents
# cd course_contents
# git checkout -b local_22_STABLE origin/MOODLE_22_STABLE

If your Moodle dirroot is git checkout too, you may want to add the block directory into the list of ignored files:

# cd /var/www/moodlesite/htdocs
# echo /blocks/course_contents/ >> .git/info/exclude

To download the block in ZIP or TAR.GZ packages, follow [https://github.com/mudrd8mz/moodle-block_course_contents/tags this page]

==Examples==

{| class="wikitable"
! <center>Start of the section summary HTML</center>
! <center>Automatic course contents line</center>

|-
| <nowiki>Welcome!<br />In this course, you will ...</nowiki>
| Welcome!

|-
| <nowiki><h1>Introduction</h1><p>In this course ...</p></nowiki>
| Introduction

|-
| <nowiki><h1><span>Lesson 1</span>: Introduction</h1></nowiki>
| Lesson 1

|}

==See also==

* [http://moodle.org/plugins/pluginversions.php?plugin=block_course_contents Plugins database record]

[[Category:Block]]
[[Category:Contributed code]]

[[es:Bloque de contenidos del curso]]

Development:Dialogue 2.0 specification

2021-07-14T13:24:39Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="wikitable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|-
| Discussion
| [http://moodle.org/mod/forum/discuss.php?d=157941 Review and comments]
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
* Teacher posts the same message to all students in ‘Course A’, future enrolled students also receive the same message. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts the same message to all members of ‘Group A’, future group members also receive the same message. Individual conversation created between teacher and each user (any role) in ‘Group A’. Multiple replies are allowed.
* Teacher posts the same message to specific students in ‘Course A’. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts a message to a specific student in ‘Course A’. Individual conversation created between teacher and specific student . Student can view but not reply. Multiple followup replies are allowed for teacher.
* Student posts a message to a specific teacher in ‘Course A’. Individual conversation created between teacher and student. Multiple followup replies are allowed.
* Teacher A leaves, Teacher B needs to manage all conversations to allow followup replies, close and delete.
* Specific Student (eg Class Rep with own role) posts a message to all students in ‘Course A’. Individual conversation created between Class Rep and each student. Multiple followup replies are allowed.
* Specific Student (eg Class Rep with own role) posts a message to a specific student in ‘Course A’. Individual conversation created between Class Rep and specific student. Multiple followup replies are allowed.
* Specific Student posts a message into a specific role (eg Class Rep role). Individual conversation created between specific student and Class Rep. Multiple followup replies are allowed.
* All Teachers can view and participate in any existing conversation in a shared teaching situation.

=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="wikitable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

<p class="note">'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.</p>

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User will see all groups listed in the recipient picker. User can open a conversation with any user or group of users.

==== Separate groups mode ====
User will see groups they are a member of listed in the recipient picker. User can open a conversation with any user in a group they are a member of.

User with capability moodle/site:accessallgroups with permission allow will see all groups listed in the recipient picker and can open a conversation with any user regardless of group membership.

<p class="note">'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.</p>

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated open conversations

=== Logging ===
Dialogue events that will be logged.
* open
* view
* viewall - index
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="wikitable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="wikitable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| message
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (10)
| 0
| flag to indicate if message has been sent to recipient, date sent
|
|-
| closed
| int (10)
| 0
| flag to indicate if conversation has been closed, date closed
|
|-
| deleted
| int (10)
| 0
| flag to indicate conversation as deleted
| Keep, retrieve only conversations not marked as deleted? date deleted
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="wikitable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
|
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| message
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="wikitable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="wikitable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| message
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| later implementation
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| later implementation
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="wikitable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
Restoring a 1.9x backup into a 2.0 Moodle? TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 08/10/2010

Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker

[[Category:Contributed code]]

Development:Google Gears integration

2021-07-14T13:24:39Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{GSOC 09}}
Project specification, Google Summer of Code 2009

'''Executive Summary:''' This project is based on the idea of [http://moodle.org/mod/forum/discuss.php?d=118015 integrating Google Gears to Moodle]. An offline mode will allow people with limited Internet connection to browse activities and other resources, take notes and store them locally, save assignments even if the user is not connected and then upload/synchronize when the user is online. Moreover, the plan is to create a working base/architecture and then make it easier to add offline functionality to any kind of Moodle activity.

== Motivation ==

Integrating Google Gears to Moodle would allow to browse the homepage and the course site while offline, and speed up the loading process while online: it stores files on the end user's computer therefore enhancing local access. It also let webs applications interact naturally with the user's desktop by storing data locally (in a database) and improving performance by running JavaScript in the background. And last but not least, it is open source.

I find this project particularly useful for communities with a slow bandwidth or where students can get online only a few times a week, download a lesson, and upload what they have worked on while offline. Other potential users would be people who travel and do not want to pay for getting online at an airport, but still continue following a course. The ability to keep learning from useful resources, even if we are not connected to the Internet, was one of my major motivations for this project. This, together with the speeding up advantage, will help Moodle's performance and usability.

== Implementation details ==

Most of the "offline" integration will be done using HTML5, as this is the long term target. At each important step, a translation to Google Gears will be created to make it accessible for users whose browsers have not implemented HTML5 yet.

=== Requirements ===

* Be able to switch to "Offline mode" at any point
** Be able to display the homepage, the course pages, course formats, and some modules (to be specified)
** Be able to follow most of the internal links
* Be able to reconnect and synchronize back to "Online mode"

=== Glossary ===

{| class="wikitable"
!Term
!Definition
|-
|Application cache
|A set of cached resources consisting of one or more resources, identified by URLs
|-
|Manifest
|A list of all the URLs to be captured. It can also contain the version for the manifest file format, the version of the contents of the manifest, and an optional redirection URL.

|}

=== To-do list ===

* Start a working flexible base/architecture for Google Gears in Moodle. Define the architecture for the web application: isolate de data layers (local and server), and the incorporation of a data switch and synchronization engine. Begin with the homepage and course page to make sure that we can handle logs and then continue with mod/resource:
** Store the HTML, CSS and Javascript in the SQLite DB provided by Gears. Use the Database class to store the data.
** Code and edit a dynamic manifest to include the resource available offline
** Make use of the LocalServer class to store an initial sample of the Moodle application on the local server. Make sure the application starts offline.
** Add the WorkerPool class to run the Javascript code in Moodle
* Submit initial code for evaluation. A student should be able to access resources offline at this point.
* Based on feedback: debug, clean code, perform more extensive tests on this base architecture.
* Add a more versatile functionality for other kinds of modules: database, choice, assignment (suggested), lesson if possible.
* Test the functionality above with a limited sample of activities. A student should be able to make changes at this point. For example:
** Download all the interface for offline visualization
** Make changes offline in a choice module
** Save changes
** Synchronize when back online and upload the choice
* Revise security holes and permissions.
* Clean code, perform final tests, and finish documentation.

=== Future Work ===

* Try the functionality to work with all other kinds of activities and a full offline Moodle.
* Allow for more flexibility when going offline: caching only by week or topic if there is limited memory
* Use the WorkerPool class to download static files in the background and speed up the user experience
* Store a local copy of the database for faster performance
* Full integration and translation between HTML5 and Google Gears
* Backward compatibility with Moodle 1.9 and earlier

==See also==

For more information, please visit the following links:

* [http://gears.google.com/ Google Gears]
* [http://tracker.moodle.org/browse/MDL-18444 Tracker issue]
* [http://moodle.org/mod/forum/discuss.php?d=118015 Main forum discussion]
* [http://moodle.org/mod/forum/discuss.php?d=107920 About OLPC and GG-based offline-moodle]
* [https://docs.moodle.org/en/GSOC/2009 Overview of the Google Summer of Code 2009 projects for Moodle]

==Screenshots==

Going offline UI: [[Image:offline-moodle-progress-bar.png]]

Offline forum: [[Image: Offline-forum-module.png]]

Development:Quiz report statistics

2021-07-14T13:24:39Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

'''These statistics are designed for use with summative tests where students have just one attempt and complete that attempt.'''

== Test statistics ==

''Average grade'': For discriminating, deferred feedback, tests aim for between 50% and 75%. Values outside
these limits need thinking about. Interactive tests with multiple tries invariably lead to higher averages.

''Median grade'': Half the students score less than this figure.

''Standard deviation'': A measure of the spread of scores about the mean. Aim for values between 12% and
18%. A smaller value suggests that scores are too bunched up.

''Skewness'': A measure of the asymmetry of the distribution of scores. Zero implies a perfectly symmetrical
distribution, positive values a ‘tail’ to the right and negative values a ‘tail’ to the left.

[[Image:Skewness.jpg]]

Aim for a value of -1.0. If it is too negative, it may indicate lack of discrimination between students who do better than average. Similarly, a large positive value (greater than 1.0) may indicate a lack of discrimination near the pass fail border.

''Kurtosis'': Kurtosis is a measure of the flatness of the distribution.

A normal, bell shaped, distribution has a kurtosis of zero. The greater the kurtosis, the more peaked is the
distribution, without much of a tail on either side.

Aim for a value in the range 0-1. A value greater than 1 may indicate that the test is not discriminating
very well between very good or very bad students and those who are average.

''Coefficient of internal consistency (CIC)'': It is impossible to get internal consistency much above 90%.
Anything above 75% is satisfactory. If the value is below 64%, the test as a whole is unsatisfactory and
remedial measures should be considered.

A low value indicates either that some of the questions are not very good at discriminating between
students of different ability and hence that the differences between total scores owe a good deal to chance
or that some of the questions are testing a different quality from the rest and that these two qualities do not
correlate well – i.e. the test as a whole is inhomogeneous.

''Error ratio (ER)'': This is related to CIC according to the following table: it estimates the percentage of the
standard deviation which is due to chance effects rather than to genuine differences of ability between
students. Values of ER in excess of 50% cannot be regarded as satisfactory: they imply that less than half
the standard deviation is due to differences in ability and the rest to chance effects.

{| class="wikitable"
|-
! CIC
! ER
|-
| 100
| 0
|-
| 99
| 10
|-
| 96
| 20
|-
| 91
| 30
|-
| 84
| 40
|-
| 75
| 50
|-
| 64
| 60
|-
| 51
| 700
|}

''Standard error (SE)'': This is SD x ER/100. It estimates how much of the SD is due to chance effects and is a
measure of the uncertainty in any given student’s score. If the same student took an equivalent test, his
or her score could be expected to lie within ±SE of the previous score. The smaller the value of SE the
better the test, but it is difficult to get it below 5% or 6%. A value of 8% corresponds to half a grade
difference on a typical scale – if the SE exceeds this, it is likely that a substantial proportion of the
students will be wrongly graded in the sense that the grades awarded do not accurately indicate their true
abilities.

== Question statistics ==

''Facility index (F)'': The mean score of students on the item.

{| class="wikitable"
|-
! F
! Interpretation
|-
| 5 or less
| Extremely difficult or something wrong with the question.
|-
| 6-10
| Very difficult.
|-
| 11-20
| Difficult.
|-
| 20-34
| Moderately difficult.
|-
| 35-64
| About right for the average student.
|-
| 66-80
| Fairly easy.
|-
| 81-89
| Easy.
|-
| 90-94
| Very easy.
|-
| 95-100
| Extremely easy.
|}

''Standard deviation (SD)'': A measure of the spread of scores about the mean and hence the extent to which
the question might discriminate. If F is very high or very low it is impossible for the spread to be large.
Note however that a good SD does not automatically ensure good discrimination. A value of SD less than
about a third of the question maximum (i.e. 33%) in the table is not generally satisfactory.

''Random guess score (RGS)'': This is the mean score students would be expected to get for a random guess at
the question. Random guess scores are only available for questions that use some form of multiple choice.
All random guess scores are for deferred feedback only and assume the simplest situation e.g. for multiple
response questions students will be told how many answers are correct.

Values above 40% are unsatisfactory – and show that True/False questions must be used sparsely in summative tests.

''Intended weight'': The question weight expressed as a percentage of the overall test score.

''Effective weight'': An estimate of the weight the question actually has in contributing to the overall spread of
scores. The effective weights should add to 100% - but read on.

The intended weight and effective weight are intended to be compared. If the effective weight is greater
than the intended weight it shows the question has a greater share in the spread of scores than may have
been intended. If it is less than the intended weight it shows that it is not having as much effect in
spreading out the scores as was intended.

The calculation of the effective weight relies on taking the square root of the covariance of the question
scores with overall performance. If a question’s scores vary in the opposite way to the overall score, this
would indicate that this is a very odd question which is testing something different from the rest. And the
computer cannot calculate the effective weights of such questions resulting in warning message boxes
being displayed.

''Discrimination index'': This is the correlation between the weighted scores on the question and those on the
rest of the test. It indicates how effective the question is at sorting out able students from those who are
less able. The results should be interpreted as follows

{| class="wikitable"
|-
! Index
! Interpretation
|-
| 50 and above
| Very good discrimination
|-
| 30 – 50
| Adequate discrimination
|-
| 20 - 29
| Weak discrimination
|-
| 0 - 19
| Very weak discrimination
|-
| -ve
| Question probably invalid
|}

''Discrimination efficiency'': This statistic attempts to estimate how good the discrimination index is relative
to the difficulty of the question.

An item which is very easy or very difficult cannot discriminate between students of different ability,
because most of them get the same score on that question. Maximum discrimination requires a facility
index in the range 30% - 70% (although such a value is no guarantee of a high discrimination index).

The discrimination efficiency will very rarely approach 100%, but values in excess of 50% should be
achievable. Lower values indicate that the question is not nearly as effective at discriminating between
students of different ability as it might be and therefore is not a particularly good question.

--[[User:Phil Butcher|Phil Butcher]] 15:53, 27 September 2010 (UTC)

Grade hiding

2021-07-14T13:24:38Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Grades}}
==Introduction==
Assessors often decide to hide grades and feedback until marking is complete and finalised, and then release them all at once.

Although Workflow allows this (and is particularly helpful where there are several multiple markers) it is sometimes quicker to simply hide the grades in the Grader Report until it is time to release them. This page explains how to do that.
{{Note|Using Show/Hide for an Assignment on the course front page has '''no effect''' on whether its grades are shown or hidden for students. The assignment and its grades are entirely independent from each other, so the grades must be show or hidden independently.}}

{{Note|If you are using the Grader Report to calculate final grades, do ensure those activities are not hidden when you carry out the calculation.}}

{{Note|Newly created activities '''do not''' inherit visibility from the grade category.}}

==Automatically hide grades and feedback until a set date==
This is useful if you have agreed a fixed date to reveal marks and feedback to students. It saves you needing to remember to do this manually (though you can manually change the date if you need to).
#In the Grader Report, turn editing on; further settings and controls display.
#In the activity's column, in its '''Controls''' row, click the '''Edit''' icon; a settings page displays.
#To reveal the settings for dates setting, click the link to '''Show more'''; further settings display.
#For the '''Hidden until''' setting, click its Enable checkbox; it becomes editable.
#Type in the date and time to reveal the marks and feedback.
#Save.

==Manually hide grades and feedback==
This is best used if you never want students to see the grades or feedback, or if you are unsure of the date on which they need to be revealed.
#To get to the Grader Report go to your Moodle course front page and in its Settings click Grades; the Grader Report displays.
#'''Turn editing on'''; further settings and controls display.
# Note that columns correspond to activities, and each column has '''Controls''' (just below the column title) which act on that entire activity.
#To hide grades and feedback for an assignment, find its column and click the '''Show/Hide''' icon in the '''Controls''' row.
#In this case there is no need to Save - the effects are immediate.

==An example of how hiding grades might be used==

{| class="wikitable"
|-
!Phase
!Hidden
![[Grade locking|Locked]]
|-
|Before the due date; participant submissions
|Yes
|No
|-
|Due date and beginning of grading/feedback
|Yes
|Yes
|-
|End of grading/feedback, release of grades
|No
|Yes
|}

[[ca:Ocultació_de_qualificacions]]
[[es:Ocultamiento de calificación]]
[[fr:Note cachée]]
[[ja:評定非表示]]
[[de:Bewertungen verbergen]]

Outcomes

2021-07-14T13:24:38Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Grades}}
==What are outcomes?==

Outcomes are specific descriptions of what a student has demonstrated and understood at the completion of an activity or course. Each outcome is rated by some sort of [[Scales|scale]]. Other terms for outcomes are 'Competencies' and 'Goals'.

In simple terms outcomes are similar to sub components of a grade. A grade is an assessment of overall performance that may include tests, participation, attendance and projects. Outcomes assess specific levels of knowledge through a series of statements, that maybe coded with numbers or letters. Thus an overall grade can be given for a course, along with statements about specific competencies in the form of outcomes.

{{Note|Moodle 3.1 includes a new feature, [[Competencies]], which enables [[Learning plans]] to be set up. It provides an alternative to outcomes.}}

==Enabling outcomes==

To enable outcomes to be used in any course on the site

# Go to ''Site administration > Advanced features''
# Tick the ''Enable outcomes'' checkbox
# Save changes

==Adding course-level outcomes==

[[Image:addnewoutcome.png|thumb|Adding an outcome]]
To add a course-level outcome:

# Click the 'Edit outcomes' link in ''Course administration > Outcomes''
# Click the 'Add a new outcome' button
# Complete the form then click the 'Save changes' button.

==Adding standard outcomes==

An administrator can add standard outcomes, which are available site-wide, in ''Site administration > Grades > Outcomes''. Multiple standard outcomes can be added using the import outcomes functionality (see below).

==Using outcomes==

# Choose or define some outcomes for your course (as described above).
# For each activity, choose which of these outcomes apply using the checkbox in the activity's settings page.
# When grading that activity, grade each student using the Outcome scales. Note: You can also edit the grades in the [[Grader report]] (useful for modules that don't feature inbuilt grading).
# Use the outcomes as part of the assessment for students, or look at the Outcomes report for some useful feedback on how students in the class in general are performing.

==How do I remove a selected outcome from an activity?==

Previously selected outcomes are greyed out on the update activity page. To remove an outcome

# Go to ''Course administration > Gradebook setup''
# Locate the outcome (below or above the activity they have been enabled in) then in the actions column click edit and then delete.

Deleting the outcome will result in the outcome being deselected on the update activity page.

==How do I change the scale associated with an outcome?==

The scale associated with an outcome can only be changed if the outcome is not selected for use with an activity.

# Go to ''Course administration > Outcomes''
# Check that the outcome has zero in the items column i.e. it is not used in any activity. If not, go to ''Course administration > Gradebook setup'' and delete all instances of the outcome.
# Return to ''Course administration > Outcomes'' and click the edit icon opposite the outcome
# Change the scale
# Click the 'Save changes' button.

==Outcomes report==

The outcomes report in ''Course administration > Grades > Outcomes report'' helps teachers monitor their students' progress using outcomes. It lists site-wide outcomes and custom outcomes used in the current course, their overall average (each outcome can be measured through many [[Grade items|grade items]]). It will show the name, course and site wide average, the activity, the average values and the number of "grades" given.

The outcomes report is a table with 6 columns:

*Short name - the short name of the outcome used in this course.
*Course average -shows two values representing the average scores given to students for each outcome used in this course.
*Site-wide - Whether the outcome is a site-wide outcome or not.
*Activities - This lists the activities that use this outcome in this course. A new row is created for each activity, and the activity name is linked to the activity's page.
*Average - the average score for each activity using the outcome in this course.
*Number of Grades - The number of grades given to students for each activity using the outcome.

==Outcomes used in course==

Outcomes may be set at site and/or course level. To choose outcomes for use in your course:

# View available standard outcomes in ''Course administration > Outcomes'' or via the gradebook Outcomes tab
# Add outcomes from the standard available list (right side), and use the left-facing arrow button to add them to outcomes used list (left side). Multiple outcomes may be selected by holding down the Apple or Ctrl key whilst clicking on the individual outcomes.

==Exporting outcomes==

Outcomes (and their associated scales) can be exported by clicking the "Export all outcomes" button. This will send a file (in .csv format) that can be read by Excel, OpenOffice.org or by any text editor.

==Importing outcomes==

Outcomes (and associated scales) may be imported by submitting a csv file. The format should be as follows:

{| class="wikitable"
|-
! Field name
! Description
! Required
! Format
|-
| outcome_name
| The full name of the outcome
| Yes
| String
|-
| outcome_shortname
| The short name of the outcome
| Yes
| String
|-
| outcome_description
| The description of the outcome
| No
| String
|-
| scale_name
| The name of the scale used
| Yes
| String
|-
| scale_items
| A comma-separated list of scale items
| Yes
| String
|-
| scale_description
| The description of the scale
| No
| String
|}

Here is an example:

outcome_name;outcome_shortname;outcome_description;scale_name;scale_items;scale_description
Participation;participation;;Participation scale;"Little or no participation, Satisfactory participation, Full participation";

To import outcomes:

# Click the 'Import outcomes' link in ''Course administration > Outcomes''
# Choose 'Import as custom outcomes (only this course)' or 'Import as standard outcomes' as required
# Upload the csv file

Note that while importing:
*Existing outcomes and scale will be used if available (no overwriting is done by the script)
*The script will stop if it detects that the file contains invalid data

==Outcomes capabilities==

* [[Capabilities/gradereport/outcomes:view|View the outcomes report]]
* [[Capabilities/moodle/grade:manageoutcomes|Manage grade outcomes]]

==See also==

* The section 'Outcome items' in [[Grade items]]
* [[Competencies]] - a new feature in 3.1 onwards
* [http://school.moodledemo.net/mod/assign/view.php?id=190&action=grade&rownum=1&useridlistid=0 See how a teacher selects Outcomes when grading a student] on the Mount Orange School demo site. (Log in with username '''teacher'''; password '''moodle''')
* [[Differentiator local plugin]] - A tool to efficiently formulate and save learning goals based on the Differentiator by Ian Byrd. Learning goal are persisted for every user in your Moodle installation.

[[Category:Report]]

[[es:Resultados]]
[[fr:Objectifs]]
[[ja:アウトカム]]
[[de:Lernziele]]

Development:Automatic Course Archival

2021-07-14T13:24:38Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

== Executive Summary ==

In order to meet various data retention policies and regulations, it would be helpful if Moodle could automatically "archive" and/or delete courses after a certain amount of time.

The goal with these changes is to allow administrators maximum flexibility (being able to set archival options on a course-by-course basis), while maintaining a good amount of simplicity (being able to set default archival options on a category-by-category basis).

== Glossary ==

To reduce confusion, some terms and definitions are presented below:

{| class="wikitable"
!Term
!Definition
|-
|Archived Course
|A course that has been made read-only to all but course and site administrators.

|}

== Database Structures ==
=== archive_courses ===

This table keeps information about when specific courses should be archived. If a course appears in this table and enabled is set to 1, it means it should be archived or deleted automatically after the specified date is reached. If not, then no automatic archiving should occur.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|"id"
|int(10)
|
|autoincrementing
|-
|"courseid"
|int(10)
|
|unique; The course that should be archived or deleted.
|-
|"archive_enabled"
|tinyint(1)
|<center>1</center>
|If automatic archiving should be enabled for this course.
|-
|"archive_date_point"
|varchar(10)
|<center>"epoch"</center>
|Can be 'epoch', 'course_end', and in the future, some other values. Stores the point from which archive_date should be compared. E.g., if 'epoch', the course should be archived <i>archive_date</i> seconds after the Unix epoch. If 'course_end', the course should be archived <i>archive_date</i> seconds after the end of the course.
|-
|"archive_date"
|int(10)
|<center>0</center>
|When the course should be archived. Is expressed as the number of seconds after archive_date_point. (If archive_date_point is set to 'epoch', this is effectively a Unix timestamp.)
|-
|"delete_enabled"
|tinyint(1)
|<center>1</center>
|If automatic deleting should be enabled for this course.
|-
|"delete_date_point"
|varchar(10)
|<center>"epoch"</center>
|Can be 'epoch', 'course_end', and in the future, some other values. Stores the point from which delete_date should be compared. E.g., if 'epoch', the course should be deleted <i>delete_date</i> seconds after the Unix epoch. If 'course_end', the course should be deleted <i>delete_date</i> seconds after the end of the course.
|-
|"delete_date"
|int(10)
|<center>0</center>
|When the course should be deleted. Is expressed as the number of seconds after delete_date_point. (If delete_date_point is set to 'epoch', this is effectively a Unix timestamp.)

|}

=== archive_category_settings ===

This table keeps information about default settings for each category. This determines what settings a course should have when it's first created in a particular category. If a category doesn't have any settings, site-wide defaults are used instead.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|"id"
|int(10)
|
|autoincrementing
|-
|"categoryid"
|int(10)
|
|unique; The category
|-
|"archive_enabled"
|int(1)
|<center>1</center>
|If automatic archiving should be enabled by default for these courses.
|-
|"archive_date_point"
|varchar(10)
|<center>"epoch"</center>
|Can be 'epoch', 'course_end', and in the future, some other values. Stores the point from which archive_date should be compared. E.g., if 'epoch', courses should be archived <i>archive_date</i> seconds after the Unix epoch. If 'course_end', courses should be archived <i>archive_date</i> seconds after the end of the course.
|-
|"archive_date"
|int(10)
|<center>0</center>
|When courses should be archived. Is expressed as the number of seconds after archive_date_point. (If archive_date_point is set to 'epoch', this is effectively a Unix timestamp.)
|-
|"delete_enabled"
|int(1)
|<center>1</center>
|If automatic deleting should be enabled by default for these courses.
|-
|"delete_date_point"
|varchar(10)
|<center>"epoch"</center>
|Can be 'epoch', 'course_end', and in the future, some other values. Stores the point from which delete_date should be compared. E.g., if 'epoch', courses should be deleted <i>delete_date</i> seconds after the Unix epoch. If 'course_end', courses should be deleted <i>delete_date</i> seconds after the end of the course.
|-
|"delete_date"
|int(10)
|<center>0</center>
|When courses should be deleted. Is expressed as the number of seconds after delete_date_point. (If delete_date_point is set to 'epoch', this is effectively a Unix timestamp.)

|}

== Archival ==

The permissions system would be modified to perform an extra check when determining if a user had access to perform an action on a course. If a user tried to perform an action that could update or change a course after the date at which it was archived, and that user did not have the (newly created) permission to 'Update Archived Courses', they would be denied access.

== Deletion ==

The cron job would be modified to check the archive_courses table and perform a final backup of and then delete any courses after they have reached their delete_date.

== Public API ==

Modules may use only functions from lib/archivelib.php which are marked as public.

===ArchiveCourse::course_is_archived($courseid)===
Returns boolean value: true if the courseid exists in the archive_courses table, that row is enabled, and the archive_date is in the past.

===ArchiveCourse::get_course_info($courseid)===
Returns associative array of archive/delete dates, whether the course is or will be archived, whether the course will be deleted, and whether the archiving is enabled for a particular course. Returns NULL if the course doesn't exist in the table, false on failure.

===ArchiveCourse::get_course_archive_date($courseid)===
Returns the archive date (as a Unix timestamp) for a particular course, NULL if the course doesn't exist in the table, false on failure. This method converts any relative archive dates to their absolute value.

===ArchiveCourse::get_course_delete_date($courseid)===
Returns the delete date (as a Unix timestamp) for a particular course, NULL if the course doesn't exist in the table, false on failure. This method converts any relative delete dates to their absolute value.

===ArchiveCourse::set_archive_options($courseid, $options_array)===
Sets archive options for a particular course (all options are not required—if not present, defaults will be used). Returns true on success, false on failure. The $option_array should have the following format:

<pre>Array(
'archive_enabled'=>[true|false]
'archive_date_point'=>'[epoch|course_end|...]',
'archive_date'=>[int],
'delete_enabled'=>[true|false]
'delete_date_type'=>'[epoch|course_end|...]',
'delete_date'=>[int],
)</pre>

===ArchiveCourse::unarchive_course($courseid)===
Sets the enabled column to false for an archived course. Returns true if the course was successfully unarchived, or if the course wasn't archived to begin with, false on failure.

===ArchiveCategory::get_defaults($categoryid)===
Returns associative array of defaults, including archive/delete dates, whether courses will be archived, and whether courses will be deleted. Returns site-wide defaults if the category doesn't have any defaults of its own, false on failure.

===ArchiveCategory::set_defaults($categoryid, $options_array)===
Sets archive defaults for a particular category (all options are not required—if not present, site-wide defaults will be used). Returns true on success, false on failure. The $option_array should have the following format:

<pre>Array(
'archive_enabled'=>[true|false]
'archive_date_point'=>'[epoch|course_end|...]',
'archive_date'=>[int],
'delete_enabled'=>[true|false]
'delete_date_type'=>'[epoch|course_end|...]',
'delete_date'=>[int],
)</pre>

===ArchiveCategory::remove_defaults($categoryid)===
Removes category defaults (site-wide defaults will be used instead for that category)

==Capabilities and Permissions==
* archive/settings:managesite - manage site-wide default settings

* archive/settings:managecategory - manage category-level default settings

* archive/settings:managecourse - manage course-level settings

* archive/courses:update - update courses even when they're archived—intended for administrators.

==Ideas for the Future==
* add a new archive/courses:view permission to determine if a user should be able to view archived courses

Analytics plugins

2021-07-14T13:24:37Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Tracking progress}}
{{Template:Update}}
Learning Analytics are any piece of information that can help an LMS user improve learning outcomes. Users include students, teachers, administrators and decision-makers.

== Moodle Plugins ==

There are a number of reports, blocks and other plugins for Moodle that provide learning analytics.

{| class="wikitable"
|-
! Plugin
! Plugin type
! Standard / Additional
! Useful for
! Description
! Reported usage*
|-
| [[:en:Logs|Logs]]
| Report
| Standard
| Teachers, Admins, Decision-makers
| Filterable log of events
| style="text-align:center;" | 71.4%
|-
| [[:en:Activity_report|Activity]]
| Report
| Standard
| Teachers
| View count of activities in course
| style="text-align:center;" | 69.1%
|-
| [[:en:Using_Activity_completion|Activity completion]], see also [[:en:Using_Course_completion|Course completion]]
| Report
| Standard
| Teachers
| Completion matrix of students and activities
| style="text-align:center;" | 66.3%
|-
| [[:en:Logs|Live logs]]
| Report
| Standard
| Teachers, Admins
| Automatically refreshing log of events
| style="text-align:center;" | 55.2%
|-
| [[:en:Feedback_activity|Feedback]]
| Activity
| Standard
| Teachers, Researchers
| Configurable survey tool
| style="text-align:center;" | 59.5%
|-
| [[:en:Quiz_statistics_report|(Quiz) Statistics]]
| Report
| Standard
| Teachers
| Student quiz performance report
| style="text-align:center;" | 53.0%
|-
| [[:en:Participation_report|(Course) Participation]]
| Report
| Standard
| Teachers
| Single student's participation in course
| style="text-align:center;" | 49.9%
|-
| [[:en:Survey_module|Survey]]
| Activity
| Standard
| Teachers, Researchers
| Set of standardised educational surveys
| style="text-align:center;" | 45.6%
|-
| [[:en:Inspire|Inspire]]
| Administrative Tool
| Additional migrating to Standard
| Teachers, Researchers
| Moodle native descriptive and predictive learning analytics
| style="text-align:center;" | n/a
|-
| [http://moodle.org/plugins/view.php?plugin=mod_questionnaire Questionnaire]
| Activity
| Additional
| Teachers, Researchers
| Configurable survey tool
| style="text-align:center;" | 45.3%
|-
| [[:en:Course_overview_report|Course overview]]
| Report
| Standard
| Admins, Decision-makers
| Comparison of participation across multiple courses
| style="text-align:center;" | 45.0%
|-
| [[:en:Course_completion_status_block|Course completion status]]
| Block
| Standard
| Students
| View of student's own completion of activities
| style="text-align:center;" | 41.4%
|-
| [http://moodle.org/plugins/view.php?plugin=block_progress Progress Bar]
| Block
| Additional
| Students, Teachers
| Time management tool for students with overview for teachers
| style="text-align:center;" | 32.0%
|-
| [[:en:Events_list_report|Events list]]
| Report
| Standard
| Teachers, Admins
| Events that can be monitored/searched in logs
| style="text-align:center;" | 28.6%
|-
| [[:en:Activity_results_block|Activity results block]]
| Block
| Standard
| Students
| Leader-board of results in single activity
| style="text-align:center;" | 26.1%
|-
| [http://moodle.org/plugins/view.php?id=82 Configurable Reports]
([https://docs.moodle.org/29/en/ad-hoc_contributed_reports A list of contributed reports])
| Block ([https://github.com/nadavkav/moodle-report_configurablereports Report] [https://github.com/nadavkav/moodle-filter_crgraph Graphs filter])
| Additional
| Teachers, Admins, Decision-makers
| Report generation and viewing
| style="text-align:center;" | 22.7%
|-
| [[Overview_report|(Gradebook) Overview]]
| Report
| Standard
| Teachers, Students
| View of student grades across activites
| style="text-align:center;" | N/A
|-
| [[Statistics]]
| Report
| Standard
| Admins, Decision-makers
| Daily activity across site
| style="text-align:center;" | N/A
|-
| [[:en:Event_monitoring|Event monitor]]
| Report
| Standard
| Teachers, Admins, Decision-makers
| Proactive, focussed monitor tool
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/view/report_customsql Ad-hoc database queries]
| Report
| Additional
| Teachers, Admins, Decision-makers
| SQL-based report generation and viewing
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/browse.php?list=set&id=20 Engagement Analytics]
| Block, Report, Activity module
| Additional
| Teachers
| Configurable engagement measurement report and block
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/view/block_dedication Course Dedication]
| Block
| Additional
| Students, Teachers
| Estimated time online for students
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/view.php?plugin=block_graph_stats Graph Stats]
| Block
| Additional
| Teachers, Admins
| Daily visits to site or course
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/view/block_gismo GISMO]
| Block
| Additional
| Teachers
| Numerous charts of student activity participation
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/view/block_xp Level Up!]
| Block
| Additional
| Students, Teachers
| Incentive-drive participation meter
| style="text-align:center;" | N/A
|-
| [http://moodle.org/plugins/report_forumgraph Forum Graph]
| Report
| Additional
| Teachers
| Graph of forum interactions
| style="text-align:center;" | N/A
|-
| [https://moodle.org/plugins/block_analytics_graphs Analytics Graphs]
| Block
| Additional
| Teachers
| Visualisation of student participation
| style="text-align:center;" | N/A
|-
| [https://moodle.org/plugins/block_heatmap Heatmap]
| Block
| Additional
| Teachers
| Colour-coded indication of activity views on course page
| style="text-align:center;" | N/A
|-
| [https://moodle.org/plugins/local_analytics Analytics]
| Local
| Additional
| Admins, Decision-makers
| Enriched feed to Google Analytics and Pywick
| style="text-align:center;" | N/A
|-
| [https://moodle.org/plugins/gradereport_gradedist Grade distribution]
| report
| Additional
| Teachers
| Visualizes the grades of students in a course
| style="text-align:center;" | N/A
|-
| [https://moodle.org/plugins/logstore_xapi Logstore xAPI]
| Logstore
| Additional
| Admins, Decision-makers, Researchers
| xAPI event stream output
| style="text-align:center;" | N/A
|}

<nowiki>*</nowiki> Reported usage is drawn from the [http://research.moodle.net/71/1/Plugins%20Usage%20Survey%202015%20Report.pdf Plugins Usage Survey from 2015].

== Integrations with Moodle ==

A number of systems integrate with Moodle to provide learning analytics information externally.

* [http://damos.world/2013/08/30/the-moodle-activity-viewer-mav-heatmaps-of-student-activity/ Moodle Activity Viewer] (MAV) ([https://github.com/damoclark/mav-enterprise Git]), consider [https://moodle.org/plugins/block_heatmap Heatmap] as an alternative
* [http://www.intelliboard.net/ Intelliboard]
* [http://www.lambdasolutions.net/products/lmsreporting/ Zoola (was Analytika)]
* [https://learninglocker.net/ Learning Locker], can be used with [https://moodle.org/plugins/logstore_xapi Logstore xAPI]
* [http://klassdata.com/smartklass-learning-analytics-plugin/learning-analytics-moodle-smartklass/ SmartKlass]
* [http://www.blackboard.com/education-analytics/blackboard-predict.aspx Blackboard Predict]
* [http://melbourne-cshe.unimelb.edu.au/research/edutech/completing-the-loop Completing the loop]
* [https://www.iadlearning.com/ IADlearning] offers institutions and educators a rich set of analytics allowing them to understand the quality of their training content, as well as the quality of the ongoing learning processes.

== Dimensions of Analytics ==

Learning analytics are a concept that has been emerging under a number of different names through the past decades. Its origins lie in research in data mining and intelligent tutoring systems. LA tools can be categorised in a number of ways:

* Descriptive
* Predictive
* Diagnostic
* Prescriptive

== See also... ==
* [https://moodle.org/mod/forum/view.php?id=8044 Analytics and reporting forum]
* [https://moodle.org/mod/forum/view.php?id=8205 Moodle Research forum]
* [[:dev:Moodle_research|Moodle research page]]
* [[Logging]]
* [[:en:Events_list_report|Events list]]
* [[:dev:Learning_Analytics_Specification|Learning Analytics API specification]]
* [[:dev:Working_Groups#Assessment_Analytics|Assessment Analytics working group details and issues]]
* [[:dev:Event_2|Events specification]]
* [[:dev:Logging_2|Logging specification]]
* [[:dev:reportbuilder/API|Report Builder API specification]]
* Use [https://moodle.org/plugins/filter_generico Generico filter] to display custom DB reports with graphs [https://moodle.org/mod/forum/discuss.php?d=324771#p1334032 Demo / Forums]
* [https://www.jisc.ac.uk/blog/solving-the-ethical-and-legal-issues-around-learning-analytics-a-series-of-podcasts-11-mar-2016 Solving the ethical and legal issues around learning analytics: a series of podcasts]

== Presentations ==
* [https://www.youtube.com/watch?v=MHv4vp1hxQc&index=5&list=TLGCVIc9g1-qUMUxOTEwMjAxNg Moodle Analytics Plans I Elizabeth Dalton at MoodleMoot Australia 2016] (video 24m)

[[Category:Report]]
[[Category:Analytics]]

[[es:Análisis del aprendizaje]]

Emoticon images

2021-07-14T13:24:37Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

The list of images that will be used to replace the emoticon text can be defined by a site administrator in ''Settings > Site administration > Appearance > HTML settings''. The images defined here are used by [[Display emoticons as images]] filter and TinyMCE HTML editor's Insert emoticon popup menu.
[[Image:emoticon-setting.png|thumb|Emoticon setting page]]

== Form table fields ==

The form table maps the emoticon characters like <code>:-)</code> to an image that will be used to display that emoticon. Images can be provided either by the Moodle core itself or by any other installed plugin (like an activity module, block, theme or your plocal plugin). For accessibility reasons, alternative texts for these images should be defined, too.

=== Emoticon text ===

Into the first column, insert the text representation of the emoticon. The emoticon filter converts these texts into images. The text must pass the following constraints:

* It must be at least two characters long
* It can not contain <code>:/</code> and <code>//</code> substring to avoid accidental breaking of URL addresses
* It must contain some non-alphanumeric character to prevent from breaking HTML tags in the text

=== Image name and component ===

The default set of emoticons are provided by Moodle core itself. In that case, the image component is set to ''core''. The image name is a relative path to a file without the trailing slash and without the file extension. The image must be located in the <code>/pix</code> folder of the given component.

''Example:'' if the image name is set to <code>s/smiley</code> and the image component is set to <code>core</code>, the image file <code>{dirroot}/pix/s/smiley.gif</code> from your Moodle installation folder is used to display that emoticon.

=== Alternative text ===

Alternative texts are taken from [[Language packs|language packs]] that can be again provided by either the core or a plugin. The first field value is the string identifier and the second field value is the name of the component providing that string (see the language packs documentation for details).

''Example:'' if the emoticon has the alternative text set to <code>smiley</code> and <code>core_pix</code>, then the localized text will be obtained from the file <code>{dataroot}/lang/XX/pix.php</code> where XX is the current language code. If that translation is available, the value from the English pack <code>{dirroot}/lang/en/pix.php</code> will be used.

''Technical note:'' these two values are passed as the parameters to the <code>get_string()</code> function to obtain the alternative text

== Custom emoticons ==

To support your own emoticons, just add another row into the form table. However, if the images and their alternative texts are not available in the Moodle yet, you will have to add them in a form of an installed plugin, typically together with a theme or via your local plugin. The following section illustrates some options how to register emoticons provided by various types of plugins.

=== Emoticon provided by activity module ===

Let us say we want to use the emoticons system to display [[Workshop module]] icon instead of <code>(workshopicon)</code> text. As you can see, the icon is located in <code>{dirroot}/mod/workshop/pix/icon.gif</code>. Just add the following row into the emoticons form table:

{| class="wikitable"
|-
! Text
! Image name
! Image component
! colspan="2" | Alternative text
|-
| (workshopicon)
| icon
| mod_workshop
|
|
|}

Save changes in the form and the icon should appear at the end of the row. If you have the emoticon filter enabled, whenever you or your users type <code>(workshopicon)</code> in the text, it will be replaced with the image.

You may want to use the localized term for the Workshop module as the alternative text for that image. Because the Workshop module already contains a string that we can use, just add the following values into the last two columns of the table and save the changes again:

{| class="wikitable"
|-
! Text
! Image name
! Image component
! colspan="2" | Alternative text
|-
| (workshopicon)
| icon
| mod_workshop
| modulename
| mod_workshop
|}

=== Emoticon provided by installed theme ===

[[Development:Themes 2.0|Themes in Moodle 2.0]] are able to override any standard image provided by the Moodle core by default. So if a file <code>{themedir}/pix_core/s/biggrin.*</code> exists it is automatically used instead of standard <code>{dirroot}/pix/s/biggrin.*</code>. Themes like any other plugins are also able to extend the standard emoticon set or change the file names or their directories.

Let us say you have installed a theme named <code>mychool</code> that comes with its own set of standard emoticons. Those emoticons must be located in the <code>/pix</code> subfolder of that theme, for example in <code>{themedir}/pix/smilies/happy.png</code>. Now you want to use the emoticons provided by this theme instead of the default Moodle emoticon set. Just replace the relevant rows in the table with the new values:

{| class="wikitable"
|-
! Text
! Image name
! Image component
! colspan="2" | Alternative text
|-
| :-)
| smilies/happy
| theme_myschool
| smiley
| core_pix
|}

Note that we replaced just the image name and component. So the alternative text will be taken from the core language pack which is probably already localized into many languages.

=== Preparing own set of emoticons ===

If you have a set of images you would like to use as emoticons at your site, we recommend you to prepare a local plugin that will just provided these emoticons, without any other functionality. Even though this way involves a bit more work at the beginning, it is preferable over direct modification of the standard Moodle files. By encapsulating your emoticon with a local plugin, you can safely upgrade your site without the risk of overwriting your modifications, deploy the local plugin at multiple servers and share your work easily with the others.

Writing a local plugin that provides a set of emoticons is not hard even if you are not experienced PHP developers. You can use a [http://github.com/mudrd8mz/moodle-local_aliens published example] as a scaffold for your own work.

[[Category:Site administration]]
[[Category:Filter]]

[[es:Imágenes de emoticones]]

Development:Gradebook settings review

2021-07-14T13:24:36Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{| class="wikitable"
|-
! Setting
! Site
! Course
! User
! Comments
|-
| Graded roles || General settings || - || - ||
|-
| Enable outcomes || General settings || - || - ||
|-
| User profile report || General settings || - || - || A confusing setting when there is only one item in the dropdown menu
|-
| Aggregation position || General settings || Course settings || My report preferences ||
|-
| Include scales in aggregation || General settings || - || - ||
|-
| Show submitted date for hidden grades || General settings || - || - ||
|-
| Enable publishing || General settings || - || - ||
|-
| Grade export display type || General settings || Grade export || - ||
|-
| Grade export decimal points || General settings || Grade export || - ||
|-
| Primary grade export methods || General settings || - || - ||
|-
| Hide forced settings || Grade category settings || - || - ||
|-
| Aggregation || Grade category settings || - || - || Force and advanced setting options
|-
| Aggregate only non-empty grades || Grade category settings || - || - || Force and advanced setting options
|-
| Include outcomes in aggregation || Grade category settings || - || - || Force and advanced setting options
|-
| Aggregate including subcategories || Grade category settings || - || - || Force and advanced setting options
|-
| Keep the highest || Grade category settings || - || - || Force and advanced setting options
|-
| Drop the lowest || Grade category settings || - || - || Force and advanced setting options
|-
| Grade display type || Grade item settings || Course settings || - ||
|-
| Overall decimal points || Grade item settings || Course settings || - || Setting is for display purposes only
|-
| Advanced grade item options || Grade item settings || - || - || For selecting which elements should be displayed as advanced when editing grade items
|-
| Students per page || Grader report settings || - || My report preferences ||
|-
| Quick Grading || Grader report settings || - || My report preferences ||
|-
| Quick Feedback || Grader report settings || - || My report preferences ||
|-
| Aggregation view || Grader report settings || - || My report preferences ||
|-
| Grades selected for column averages || Grader report settings || - || My report preferences ||
|-
| Show calculations || Grader report settings || - || My report preferences ||
|-
| Show show/hide icons || Grader report settings || - || My report preferences ||
|-
| Show column averages || Grader report settings || - || My report preferences ||
|-
| Show groups || Grader report settings || - || My report preferences ||
|-
| Show locks || Grader report settings || - || My report preferences ||
|-
| Show ranges || Grader report settings || - || My report preferences ||
|-
| Show user profile images || Grader report settings || - || My report preferences ||
|-
| Show user idnumber || Grader report settings || - || My report preferences ||
|-
| Show activity icons || Grader report settings || - || My report preferences ||
|-
| Show number of grades in averages || Grader report settings || - || My report preferences ||
|-
| Column averages display type || Grader report settings || - || My report preferences ||
|-
| Range display type || Grader report settings || - || My report preferences ||
|-
| Decimals in column averages || Grader report settings || - || My report preferences ||
|-
| Decimals shown in ranges || Grader report settings || - || My report preferences || Setting may be overridden per grading item
|-
| Show rank || Overview report settings || Course settings || - ||
|-
| Show rank || User report settings || Course settings || - ||
|-
| Show percentage || User report settings || Course settings || - || In Moodle 1.9.3 onwards
|-
| Show hidden items || User report settings || Course settings || - ||
|}

[[Category:Grades]]

Event monitoring

2021-07-14T13:24:35Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Course reports}}

==What is event monitoring?==
*Event monitoring allows admins and teachers to receive notification when certain events happen in Moodle. See [[Events list]] for examples of events and their levels. Note that students may also be allowed to subscribe to rules if they are given the capability ''tool/monitor:subscribe''. It is not recommended that they be allowed to create or manage rules.
*To do this, a 'rule' needs to be created for the event to be monitored and then a user, such as the admin or teacher will need to subscribe to it to be notified.
*The rule will specify what the event is and how often it must happen before notification is sent to the subscriber. The notification may be pop-up, email or other chosen methods.
*A teacher can create a rule from ''Course administration > Reports > Event monitoring rules'' and an administrator can, additionally, create a rule from ''Site administration > Reports > Event monitoring rules.''
*You can subscribe to available rules via the user menu ''Preferences > Event monitoring''.

{{MediaPlayer | url = https://youtu.be/YkuK2w1lJnk}}

==Enabling event monitoring==

Event monitoring is disabled by default because of performance issues. An administrator can enable it from ''Site administration > Reports > Event monitoring rules''.

==How to create or manage a rule==

As a course teacher, go to ''Course administration > Reports > Event monitoring rules'', or as an admin go to ''Site administration > Reports > Event monitoring rules''.

===Rule name===

You can call the rule what you like but it should be something others will understand as they may wish to subscribe to the rule you created.

===Area to monitor===

When you select an area to monitor, for example, ''Forum'', the 'Event' drop down menu below will then display the events you can select from.

===Event===

Once an area has been chosen, the events for that area will display here.

===Description===

You don't have to use a description but if you do, it should be something meaningful to others as they may wish to subscribe to the rule you created.

===Notification threshold===

*This means: ''how many times should this event happen before I get notified?''
*For example the following setting would mean that if an event happens five times in 30 minutes then Moodle will send you an alert:
[[File:notificationthreshold.png|center]]

===Notification message===

When creating or editing a rule, you can embed placeholders to add details to notification messages. The use of placeholders is optional; you can use any personalised message, but if you wish to use placeholders, there are examples of use below:

The placeholders that can be used in a message template are as follows:
{| class="wikitable"
! Placeholder
! What it does
! Example
|-
| '''{link}'''
| Direct link to the actual event, eg a forum discussion.
| <nowiki>http://YourMoodle.com/mod/forum/discuss.php?d=2</nowiki>
|-
| '''{modulelink}'''
| Link to the module where the event has happened, eg a forum
| <nowiki>http://YourMoodle.com/mod/forum/view.php?id=8</nowiki>
|-
| '''{rulename}'''
| A name for the rule.
| Student discussions
|-
| '''{description}'''
| A description of the rule.
| I want to receive notifications when there is a large volume of student posts in a discussion.
|-
| '''{eventname}'''
| The name of the event being monitored.
| Forum post created.
|-
|}

====Example 1====

The above example shows the placeholders for a rule to monitor the '''Forum post created''' event. The notification message using these placeholders would be as follows:

The rule '''{rulename}''', monitoring the event '''{eventname}''', has just been fulfilled.
Click the following link to go to the forum discussion: '''{link}'''
Rule description: '''{description}'''

The result would display like this:

The rule Student discussions, monitoring the event Forum post created, has just been fulfilled.
Click on the following link to go to the forum discussion: http://YourMoodle.com/mod/forum/discuss.php?d=2 .
Rule description: I want to receive notifications when there are a large volume of student posts in a discussion.

====Example 2====

Let's create a rule called '''Glossary entries''' to monitor when a new glossary entry is created:

The rule '''{rulename}''', monitoring the event '''{eventname}''', has just been fulfilled.
Click the following link to go to see the new entry created: '''{link}'''
Rule description: '''{description}'''

The result would display like this:

The rule Glossary entries, monitoring the event Entry has been created, has just been fulfilled.
Click on the following link to go to see the new entry created: http://YourMoodle.com/mod/glossary/view.php?id=5&mode=entry&hook=1.
Rule description: I want to receive notifications when a new glossary entry is created.

'''Note:''' Some events do not have a link. '''Course deleted''' and '''Course module deleted''' for example, would not display any link if '''{link}''' or '''{modulelink}''' is used.

==How to subscribe to a rule==

*When events are created from ''Site'' or ''Course administration > Reports > Event monitoring rules'', users who have permission to subscribe to rules have an 'Event monitoring' link on their preferences page
*From here, you can unsubscribe to any events you are subscribed to already and you can subscribe to new events created by you or others.

[[File:EMSubscriptions.png|thumb|center|500px]]

==See also==

* [[Events list report]]

[[es:Monitoreo de eventos]]
[[de:Event-Beobachtung]]

ownCloud Repository

2021-07-14T13:24:35Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Infobox plugin
|type = Repository
|entry = https://moodle.org/plugins/repository_owncloud
|tracker = https://github.com/learnweb/moodle-repository_owncloud
|discussion =
|maintainer = [[User:University of Münster|University of Münster]]
|float = right
}}

[[Category:Repositories]]
[[Category:OAuth 2]]


=General=
This repository enables Moodle users to have direct access to their private files from ownCloud in the ''Moodle file picker'' and the ''URL resource module'',
enabling to upload files into Moodle directly from their ownCloud,
without having to download it to their local machine first.

Is your institution using multiple ownCloud servers? Don't worry, a Moodle administrator can connect multiple ownCloud servers that are then presented separately to the users. Tech-savvy users are not able to add their own ownCloud servers, though, so the Moodle admin is always in control which servers are connected.

'''Are you using Nextcloud?''' ownCloud and Nextcloud share the same history. As a consequence, they work quite similar. This repository was developed with ownCloud in mind, but it actually works with Nextcloud as well. Remaining limitations have been resolved with Nextcloud 13.0.1 (see [[#Nextcloud_Limitations|Nextcloud Limitations]] for details).

=Installation=

This plugin requires configuration in ownCloud (add Moodle as an allowed client) as well as in Moodle (add ownCloud servers to which users will be able to connect). Fair warning: The configuration might become very technical. We collect a list of [[#Troubleshooting|known problems and hints at their resolution]] below.

== Add Moodle as a client to ownCloud ==
''Prerequisites: Current ownCloud installation (recommended: version 10.0.1+) with enabled HTTPS and the [https://marketplace.owncloud.com/apps/oauth2 ownCloud OAuth 2 app].
Alternatively, a current Nextcloud installation (recommended: version 13.0.1+) on HTTPS.''

Log in as an administrator. Go to '''''Settings ► User authentication''''' and add your Moodle installation as a client:

{| class="wikitable" style="vertical-align:middle;"
|-
! Name
! Redirection URI
|- style="vertical-align:middle;"
| Your Moodle name
| Your Moodle URL + '''/admin/oauth2callback.php'''
|}

For example, if your users reach Moodle at <nowiki>https://moodle.example.com</nowiki>,
your redirection URI would be <nowiki>https://moodle.example.com/admin/oauth2callback.php</nowiki>.
The name can be chosen freely, but note that it will presented to ownCloud users,
so the name should be self-explanatory to them.

After adding the client, the table displays a corresponding Client Identifier and a secret.
Those will be required for the configuration in Moodle, so keep them at hand.
For example, if your users reach Moodle at <nowiki>https://moodle.example.com</nowiki>,
your redirection URI would be <nowiki>https://moodle.example.com/admin/oauth2callback.php</nowiki>.
The name can be chosen freely, but note that it will presented to ownCloud users,
so the name should be self-explanatory to them.
After adding the client, the table displays a corresponding Client Identifier and a secret.
Those will be required for the configuration in Moodle, so keep them at hand.

== Install this plugin to Moodle ==
Copy the content of this repository to '''''repository/owncloud'''''.
No additional settings are displayed to the admin when installing the plugin.
However, when the repository is enabled, the admin has to select an issuer which defines the ownCloud server.
The next steps describe how the necessary issuer is created in Moodle's central OAuth 2 services settings.
Afterwards, an ownCloud repository instance is created using that issuer.
==Create OAuth 2 Issuer==
You need to configure Moodle so that it knows how to talk to your ownCloud server.
For this, a so-called OAuth 2 issuer has to be registered in the admin menu '''''Site administration ► Server ► OAuth 2 services'''''.
There, select '''''Create custom service'''''.
Choose the name freely; it will only be shown to you.
Enter ClientID and Secret from the ownCloud settings of [[#Add_Moodle_as_a_client_to_ownCloud|Add Moodle as a client to ownCloud]].
Enable the "Authenticate token requests via HTTP headers" checkbox.
As Service base URL, enter the full URL to your ownCloud installation, including a custom port (if any).
For example, if the ownCloud installation is at <nowiki>https://owncloud.example.com:8000/oc/</nowiki>, then this is the base URL.
Ignore the other settings and click '''''Save changes'''''.
Afterwards, your issuer is listed in a table.
There, click '''''Configure endpoints''''' to configure the services that we want to use, as ownCloud does not support auto discovery.
For the ownCloud Repository plugin four endpoints have to be registered that are ownCloud-specific:
{| class="wikitable"
|-
! Endpoint name
!Endpoint URL
|-
| token_endpoint
| Base URL + '''/index.php/apps/oauth2/api/v1/token'''
|-
| authorization_endpoint
| Base URL + '''/index.php/apps/oauth2/authorize'''
|-
| webdav_endpoint
| Base URL + '''/remote.php/webdav/'''
|-
| ocs_endpoint
| Base URL + '''/ocs/v1.php/apps/files_sharing/api/v1/shares'''
|-
| userinfo_endpoint
| Base URL + '''/ocs/v2.php/cloud/user?format=json'''
|}
{{Note|Previously, an additional parameter in the ocs_endpoint URL was listed <nowiki>(?format=xml).</nowiki> This is no longer necessary, however, having the parameter set would not result in any problems either.}}
Given the Base URL example above, an exemplary ''token_endpoint'' URL is
<nowiki>https://owncloud.example.com:8000/oc/index.php/apps/oauth2/api/v1/token
</nowiki>.
Return to the issuer overview and click on '''''Configure user field mappings'''''. Enter the following mappings:
{| class="wikitable" style="text-align: center"
|-
! External field name
! Internal field name
|-
| '''ocs-data-email'''
| '''email'''
|-
| '''ocs-data-id'''
| '''username'''
|}
This is sufficient to use basic functionality of the ownCloud repository!

Optional: If you want to use access controlled links, you also need to [[OAuth_2_services#Connecting_a_system_account|connect a system account]].
This must be an ownCloud account that does ''not'' belong to a particular person. Instead, it should be owned by Moodle.
First, create such an account in ownCloud or ask your ownCloud administrator to do so.
Choose a strong, ideally random password and do not give it to someone else who is not an administrator of your Moodle.
Afterwards, in the issuer overview, click on '''Connect to a system account'''.
Make sure that you are logged in to ownCloud ''with that account'' and '''Authorize''' Moodle.
You should then be back in the issuer overview, where you can verify that you connected the right account by checking its username.
(In your browser, log out of ownCloud now to avoid using the system account by accident.)
Also, ''do not change the system account'' after the plugin has been used. This will break all access controlled links that were created prior to a change.

For further information on configuring OAuth 2 clients visit the [[OAuth_2_services|Moodle documentation on OAuth 2]] and the [[dev:OAuth_2_API|Developer documentation on OAuth 2]].

== Create a repository instance ==
Now that the ownCloud issuer is configured, it can be associated with an instance of the repository.
Go to the repository settings '''''Site administration ► Plugins ► Repositories ► Manage repositories'''''
and enable the ownCloud respository ('''''Enabled and visible''''').
When asked for special user permissions, do not check any boxes. As they may not configure OAuth 2 issuers, these permissions are not that useful.
Then, open the '''''Settings''''' of the ownCloud repository and click '''''Create a repository instance'''''.
Enter a name that will be displayed to Moodle users and select the configured issuer.
A text underneath the select box tells you which issuers are suited for use with this repository.
If your issuer does not show up, double-check the issuer settings; particularly all URLs (base URL and endpoints) and the names of the endpoints.
[[Image:owncloudconfig.png|frame|center|Issuer instance configuration]]

You can also define the '''Name of folder''' that will show up in users' private file storage once they open access controlled links:
A share in ownCloud will always result in a file showing up at the user, so this is where that file will go in order to avoid cluttering their document root.
The dropdowns allow you to define how the repository may interact with files:
'''Supported files''' allows you to restrict usage of the repository, i.e., to allow linking ("external") only or upload ("internal") only, but you can also allow unrestricted usage.
If '''Internal and external''' is selected, you can define the default type presented to users.

Afterwards, everything is configured and ready to go! Let's see what this looks like for your users:

=Usage=
The repository is available in all activities where the file picker is used.
However, course admins can disable it in the '''''Course Administration ► Repositories''''' menu.
In the file picker a login button is displayed (assuming that the user is not authenticated yet):
[[Image:filepickerlogin.png|frame|center|File Picker Login]]
When the button is clicked a pop-up window or a new tab is opened and the user will be requested to login at the ownCloud instance and authorise access from Moodle.
If authorisation is granted, the user sees a tabular listing of the files available:
[[Image:filepickerlisting.png|frame|center|File Picker Listing]]
Here the user can select files, reload the content and logout. The settings button opens the ownCloud web interface in a new window so that you can manage your files easily

==Access controlled links==

Students may submit files from ownCloud/Nextcloud as 'access controlled links' in [[Using Assignment|assignments]]. Once submitted, the student may no longer change them, but the teacher is allowed to edit them.

Teachers may display files from ownCloud/Nextcloud as 'access controlled links'. The teacher can then continue updating the files, but students can only view them.

To enable this feature, ensure that:

# A system account has been connected in [[OAuth 2 services]] in Site administration. This account will own and control access to files submitted by students and teachers. Teachers will be able to edit the files but students will not. This should be a dedicated account for this purpose.
# "Supported files" is set to "Internal and External".
# Optional: "Default return type" is set to "External (only links stored in Moodle)".

=Nextcloud Limitations=

In 2018, Nextcloud created and published a set of fixes that resolve all known limitations. Before that, Nextcloud (up to and including version 12) had a limitation that prevented the use of file links. That means, files could only be uploaded from Nextcloud into Moodle, but you could not use the alternative, i.e. creating a file link, because the Nextcloud server would block you from doing so. Should you run into this issue, make sure that you are working with the latest version of Nextcloud (definitely not older than 13.0.1!). If that does not help, please check the [[#Troubleshooting]] section below.

With the introduction of Access Controlled Links (similar to the functionality of the [[Google_Drive_repository#Access_controlled_links|Google Drive repository]] and [[OneDrive_repository#Access_controlled_links|OneDrive repository]] plugins) in v3.5-r2 of this plugin, Nextcloud poses a new limitation. Whenever you authorise Moodle to access your Nextcloud, you log out at the browser at the same time. To access an access controlled link file you first have to authorise Moodle, then re-login in to Nextcloud in the browser. Then you can access the file from Moodle.

=Troubleshooting=

Installing and configuring this plugin is a rather technical endeavour, given that making two machines speak to each other is a very technical topic. If something goes wrong, it may be hard to find out the root cause. Nevertheless, so far we have been able to resolve all issues and, once the plugin is installed and configured correctly, it runs smoothly and very stable. The following is a list of issues that were encountered during configuration, and hints at how to proceed.

; I cannot connect a system account. : Make sure the system account is different from all personal accounts. It has to be an account that belongs to Moodle, not to a person. Look at the issuer settings. The checkbox '''Authenticate token requests via HTTP headers''' must be enabled!
; Authentication seems to have succeeded, but the filepicker shows "There are no files". : The Apache server that hosts your ownCloud may be misconfigured. Its Apache logs may show a 401 error as well if you try to see the files in Moodle. Please have a look at the comments following https://github.com/learnweb/moodle-repository_owncloud/issues/26#issuecomment-343521986 to get ideas on how to solve this. '''Alternatively''', it is possible that HTTPS is not configured correctly on the Nextcloud end. You need a valid and trusted certificate for your Nextcloud server. It is not possible to manually define exceptions, unlike in the browser.
; I can only upload files, not link to files. : Are you using Nextcloud? In that case, upgrade Nextcloud to version 13.0.1 or later. Prior to that, Nextcloud suffered from technical limitations that prevented file linking.
; If I link to files in Nextcloud I get "A request to ownCloud has failed<nowiki>:</nowiki> Invalid response". : Please double-check the URL that you entered for '''ocs_endpoint'''. Until repository_owncloud v3.5-r1 it was essential that '''?format=xml''' was specified at the end of the URL.
; After signing in with ownCloud I get an error that says "This request is not valid. Please contact the administrator of [your Moodle Name] if this error persists.". : You might have entered the wrong ''Redirect URI'' in ownCloud. It is important that it has '''/admin/oauth2callback.php''' at the end, and that it corresponds '''exactly''' with what Moodle is going to send to ownCloud when attempting to authenticate!
; When I access an access controlled link I authorise Moodle but then cannot see the file. : In Nextcloud before 14.0.1, when you authorise Moodle, your Nextcloud browser session ends. This is a special limitation of Nextcloud. You have to re-login in the browser to access the file. Starting with Nextcloud 14.0.1, this issue is resolved.
; Since I installed the plugin and connected a system account, Moodle is very slow : Nextcloud has a brute-force protection that is somewhat naïve. When enabled, it slows down some Moodle requests in some cases (even though the Moodle plugin is definitely not going to brute-force your Nextcloud!), but you can change this. First, update to the newest version of the repository plugin, as it reduces the number of requests to Nextcloud. Second, download the [https://apps.nextcloud.com/apps/bruteforcesettings "Brute-force settings" app in Nextcloud]. After installation, add the IP of your Moodle server to the whitelist.

Please add to this list if you were able to solve another issue, this will help others greatly! Thanks!

= Acknowledgement =
This plugin was originally created by Information Systems students in the project seminar sciebo@Learnweb
at the University of Münster in 2016/17. See [https://github.com/pssl16 their github page] for an archive(!) of their great work. They also [https://owncloud.org/blog/introducing-oauth2-secure-authorization-flow/ created the OAuth 2 interface for ownCloud] (featured on [https://www.heise.de/security/meldung/Sichere-Anwendungsautorisierung-ownCloud-fuehrt-OAuth-2-0-ein-3874871.html heise Security (German)]); otherwise all this wouldn't have been possible.
Learnweb (University of Münster) is maintaining the Moodle plugins since 2017.

Development:Grading interface 2.0

2021-07-14T13:24:34Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Work in progress}}
{{Moodle 2.0}}

==Objectives==

The goals of Grading Interface 2.0:

* Remove redundant per module grading interfaces.
* Use a consistent approach for all grading throughout Moodle

==Overview==

The Grading Interface 2.0 provides a user interface to add and edit grades. It will consist of a single page within /grade (the gradebook) to which all modules direct the user to perform grading.

==Interface==
The interface will be similar to mod/assignment/submissions.php Further UI improvements can be made once the underlying architecture has been implemented.

The new grading interface will replace each module's internal grading interface. For example within the assignment module on mod/assignment/view.php?id=9 (for example) there is a link that says "View N submitted assignments" that links to mod/assignment/submissions.php?id=9 where 9 is the PK of a row in the course_modules table. This would be replaced with a link to grade/submissions.php?id=9.

[[Image:GradingUI.gif]]

When the teacher clicks on "Grade" to grade an individual submission no popups should be required. If Javascript is available, use a lightbox to display the submission grading interface. If Javascript is not available replace the whole page. Adding new questions already behaves this way so for example of how this is implemented look at /question/editlib.php function create_new_question_button() and question/qbank.js init_container().

[[Image:GradingUIIndividual.gif]]

==Code Structures==

==Database Structures==
New tables to be created
===Grade===

{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this grade.
|-
| contextid
| int(10)
|
| The context id defined in context table. Is this the correct way to join the grade with the assignment/quiz?
|-
| grade
| int(10)
|
| The grade
|-
| userid
| int(10)
|
|
|-
| timecreated
| int(10)
|
|
|-
| timemodified
| int(10)
|
|
|}

The following tables need to be migrated then removed:
* quiz_grades

The following fields need to be migrated then removed:
* assignment_submission.grade

Installation FAQ

2021-07-14T13:24:34Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Installing Moodle}}
== System information needed for Installation problems forum ==
When posting questions to the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum], try to provide as much background information as possible about your Moodle system. Consider providing some or all of the following:
* Server Operating System name (version also if possible):
* PHP version (e.g. PHP 5.4.4)
* Database server type and version (e.g. MySQL 5.5.18)
* Browser and version (e.g. Firefox, IE8):
* Moodle version (e.g. 3.0):
* Moodle install type? (New/Upgrade):
* Moodle config.php attached (please remove passwords):
* Phpinfo attached?:

Make sure you provide a sensible description (never HELP! or URGENT!) and a full description of what you did and what happened. Copy and paste any error messages accurately in full. 'Nothing' is not a symptom, even a blank page is something!

[[#top|Top]]

==PHP - is it installed and what version do I have?==

Make a new file on your web site called ''info.php'', containing the following text, and call it from your browser:

<code php>
<?PHP phpinfo() ?>
</code>

If nothing happens then you don't have PHP installed or your webserver is not configured to handle .php files properly. See the installation docs for some information about where to download it for your computer. See the [[phpinfo]] page for details about the content of this page.

[[#top|Top]]

==I am being told that I need the '''intl php plugin''' to continue to install Moodle 2.x==
The intl.dll from Zend is part of the PHP 5.2.8 release and later. It is aimed at improving the internationalization of php pages and Moodle 2.x uses it as part of this process. If your install is on a local machine or network, then you can download the latest version of PHP and update your PHP. You then have to uncomment all the required dynamic extensions you need, including the php_intl.dll extension. The problem is then solved. If the install is on a host server, then you need to contact your host and ask them to do the same. As an alternative, you can unzip/untar the download file, copy and paste the intl.dll file to your php/ext folder and include the line:
extension=php_intl.dll
in the Dynamic Extensions section of your php.ini file.

You can also set the error level using:
intl.error_level = E_WARNING
but this is not essential

If you are using a Linux install, use your system package manager or specify compilation flag.
* Debian 5.0 (& Ubuntu) use: apt-get install php-intl or apt-get install php5-intl
* CentOS 5.5 (& RedHat) you should (probably) be using php 5.3 from remi and then use: yum install php-intl

This technique can be applied to any updated dynamic extension from Zend. You may want to use later dll files in your php/ext folder, you can do so by doing the same as above, but be careful, your version may not be able to take full advantage of the extension, or some very new extensions may cause an unexpected instability. The best option is still to update on a regular basis, perhaps once a year or so for the PHP.

[[#top|Top]]

===What Dynamic Extensions do I really need uncommented in my php.ini file? What else do I need to change?===
This assumes you have complete control over the installation and running of your server, if your Moodle is hosted, you need to do something different, which is also discussed below. In the php.ini you need to delete the semi-colon, the ;, from the start of any line to uncomment it. For Moodle, you really should only need to change some values, and make sure the extensions you require are available. These are:

Resource Limits
memory_limit = 128M //This is the maximum it requires and on a shared server you may get much less.

Data Handling
post_max_size = 512M //This allows postings of up to 512MB, but set it to suit yourself and your circumstances

Paths and Directories
doc_root ="driveletter:\path\to\server\active\web\directory" (e.g. d:\Apache\htdocs or e:\iis\wwwroot )
and
extension_dir = "driveletter:\path\to\php\ext" (e.g. d:\php\ext or e:\iis\php\ext)

File Uploads
upload_max_filesize = 512M (This is different from the post_max_size this is for file uploads.)

Dynamic Extensions ('''Windows Only''')
{| class="wikitable"
|-
! PHP 5.3.x
|-
|
extension=php_curl.dll
extension=php_gd2.dll
extension=php_gettext.dll
extension=php_intl.dll
extension=php_imap.dll
extension=php_ldap.dll
extension=php_mbstring.dll
extension=php_exif.dll ; Must be after mbstring as it depends on it
extension=php_mysql.dll
extension=php_mysqli.dll
extension=php_openssl.dll
extension=php_pdo_mssql.dll
extension=php_pdo_mysql.dll
extension=php_soap.dll
extension=php_sockets.dll
extension=php_sqlite.dll
extension=php_xmlrpc.dll
extension=php_zip.dll
|}

These edits and Dynamic extensions cover a range of options here, there are a number of other possibilities, but these listed are the most common ones. Unless you have a specific need, there may not be any reason to deviate from these settings, but if you do, make sure you know what is going to happen. These extensions will also allow you to successfully install and run many other PHP applications.

One example is the Oracle extensions are not shown here, but Oracle can be used for the Moodle database. Another area people often get themselves into trouble is using "Magic quotes". Magic quotes really should be set to off, they were only introduced early in the use of PHP to allow for some inexperienced scripting practices, (read poor, shoddy or dodgy here). If someone is still writing poor scripts, then they deserve to draw attention to themselves and their scripts deleted.

[[#top|Top]]

==What & where are Moodle's configuration settings stored?==
Configuration settings are stored in the config.php file stored in your moodle folder. This file is created during the installation process. If there is a problem and the installation cannot create the file, you can try creating it manually from the [[Configuration file]] docs.
[[#top|Top]]

==Downloading previous releases of Moodle==

Previous versions of Moodle that are not found on [http://download.moodle.org Moodle downloads] may be downloaded from <nowiki>http://download.moodle.org/stable[version_number]/</nowiki> where [version_number] is the number without a point. For example http://download.moodle.org/stable22/ or http://download.moodle.org/stable27/

You'll see a directory tree with the files displayed. Click on the one you want and download as normal. If you require the latest update of the version, scroll to the end of the list and download the "moodle-latest" file.

* '''Windows Packages''': To download other releases not found in [http://download.moodle.org/windows/ Moodle packages for Windows], use this URL:
:<nowiki>http://download.moodle.org/windows/MoodleWindowsInstaller-latest-[version_number].zip</nowiki>
* '''Mac Packages''': To download other releases not found in [http://download.moodle.org/macosx/ Mac packages], use either of these URLs (depending on whether you need the Intel or PPC package):
:<nowiki>http://download.moodle.org/macosx/Moodle4Mac-Intel-[version_number].dmg</nowiki>
:<nowiki>http://download.moodle.org/macosx/Moodle4Mac-PPC-[version_number}.dmg</nowiki>

For details of how to download a particular weekly version, see the post [https://moodle.org/mod/forum/discuss.php?d=346698#p1398162 Looking for VERY specific release of older Moodle].

[[#top|Top]]

== How to enable and check PHP error logs==
PHP can be set up to log errors in a variety of different ways: two of these involve the use of the php.ini file and the ini_set command. See [[dev:PHP error logs|PHP_error_logs]].

== "Could not find a top level course" ==
If this appears immediately after you have attempted to install Moodle it almost certainly means that the installation did not complete. A complete installation will ask you for the administrator profile and to name the site just before it completes. Check your logs for errors. Then drop the database and start again. If you used the web-based installer try the command line one. Does your computer definitely have sufficient resource to run Moodle?

==Email copies are not being sent from my forums==

You ''must'' set up cron properly if you want Moodle to send out automatic email from forums, assignments etc. This same process also performs a number of clean-up tasks such as deleting old unconfirmed users, unenrolling old students and so on. Please refer to the [[Cron|cron instructions]].

Tips:
* Try the default settings in '' Site administration > Server > Email''. This generally works. Except...
* On a Windows server you *must* supply the address of an SMTP server (Windows, unlike Unix, does not have a build in mail server) in the above settings page
* Make sure that ''allowuseremailcharset'' in ''Site administration > Server > Email > Outgoing mail configuration'' is set to No unless you really know what you are doing. Setting this to Yes can cause a problem in some versions of Moodle.
* Check your firewall or ask your network administrator. Many mail servers are heavily locked down and you may need permission to send mail through them.

[[#top|Top]]

==I can't log in - I just stay stuck on the login screen==

This may also apply if you are seeing “Your session has timed out. Please login again” or "A server error that affects your login session was detected. Please login again or restart your browser" and cannot log in.

The following are possible causes and actions you can take (in no particular order):

* Check first that your main admin account (which will be a manual account) is also a problem. If your users are using an external authentication method (e.g. LDAP) that could be the problem. Isolate the fault and make sure it really is Moodle before going any further.
* Check that your hard disk is not full or if your server is on shared hosting check that you have not reached your disk space quota. This will prevent new sessions being created and nobody will be able to log in.
* Carefully check the permissions in your 'moodledata' area. The web server needs to be able to write to the 'sessions' subdirectory.
* Your own computer (not your Moodle server) may have a firewall that is stripping referrer information from the browser. Here are some instructions for fixing [http://service1.symantec.com/SUPPORT/nip.nsf/46f26a2d6dafb0a788256bc7005c3fa3/b9b47ad7eddd343b88256c6b006a85a8?OpenDocument&src=bar_sch_nam Norton firewall products].
* Try deleting the ''sessions'' folder in your moodledata directory (anybody currently logged in will be thrown out)
* Try deleting cookies on your computer and/or try another browser or another client computer
* In ''Settings > Site administration > Server > Session Handling'', try setting a value for 'Cookie prefix'. You can also do this by setting <code>$CFG->sessioncookie='something';</code> in config.php. This is especially true if you are using multiple Moodles on the same browser.
* Make sure you have not removed or changed the [[Password salting|Password Salt]] value(s) in config.php. If passwords were created using a salt the correct salt must be in config.php for those passwords to continue to work. This is easily done if you recreate config.php while performing an upgrade and forget to transfer the salt values.
* Do you have a .htaccess file in your Moodle folder (or its parent directories). If so, is there anything in there that might be causing trouble (strange redirects, access restrictions etc.)?
* Check the value of '''mnet_localhost_id''' in the mdl_config database table. It's normally 1 but must match the '''mnet_hostid''' field in your user records in the mdl_user table for the user to be recognised. It can sometimes get changed spuriously during upgrades or site migrations.
* Check config.php - it should NOT have any spaces/new lines at the end of code.
* You are using the correct username and password, yes?

If you are still having problems, read the [[Can_not_log_in | Cannot log in]] page. You '''could''' also try changing the admin password. Proceed as if you have lost it - see [[Administration FAQ]].

[[#top|Top]]

==I log in but the login link doesn't change. I am logged in and can navigate freely.==

Make sure the URL in your <code>$CFG->wwwroot</code> setting is exactly the same as the one you are actually using to access the site.

[[#top|Top]]
==Uploaded files give "File not found"==

For example: Not Found: The requested URL /moodle/file.php/2/myfile.jpg was not found on this server.

This indicates that slash arguments are not enabled on your web server. Please see [[Using slash arguments]] for details.

[[#top|Top]]

==Why are all my pages blank?==

Check the dirroot variable in ''config.php''. You must use complete, absolute pathnames (e.g.)

<code php>
$CFG->dirroot = "/var/www/moodle";
</code>

Another reason might be that PHP has not been configured to support MySQL (or whatever other database you are using). This is common on RedHat and OpenBSD installations. In this case, an error is generated, but since error displays are often disabled by default, all that is seen on the browser is a blank screen. To enable PHP error displays see [[Installation_FAQ#How_to_enable_and_check_PHP_error_logs | How to enable and check PHP error logs]].

To determine if database support is your problem, insert this as the second line in your ''config.php'' file

<code php>
phpinfo();
</code>

then reload the web page. Examine the output closely to see if you chosen database is supported. If not, look for a package you are missing.

[[#top|Top]]

== Why is a particular page blank or incomplete? ==

*'''Check your web server log files!!'''
:If a particular page is blank or incomplete (it doesn't display the footer), before you do anything else switch on [[Debugging]] and [[Installation_FAQ#How_to_enable_and_check_PHP_error_logs | check your PHP error logs]]. Having established that PHP error logging is working, reproduce the error. Immediately check the error log file right at the end. Hopefully you will see a PHP error message at or very near the end of the file. This may solve your problem directly or makes it a lot easier to diagnose the problem in the Moodle forums.

*If you are '''upgrading to a new version of Moodle''', check that you do not have an old version of a non-standard block or module installed. Remove any such blocks or modules installed using the admin settings page and start the install process again. However, do also make sure that you have included all optional plugins that were required by your courses. This is particularly common with "editing on".

*If you '''do not see any blocks listed''', turn editing on and remove any blocks that you have added to that page and try reloading.

*You may get this error immediately after '''selecting a language'''. At this stage of the installation process your Moodle computer may need to connect to the Internet and download a language pack, so check that the computer can access the Internet by using a browser. Check also that your PHP settings are as given in the Moodle [[Installing_Moodle#Requirements | Moodle Requirements]] page.

'''See also''':
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=97734 PHP configuration error] forum discussion

==Installation hangs when setting-up database tables==
Sometimes the installation will hang when setting up tables, where only half the page displayed in the browser and/or other outputs are removed. You may see truncated MySQL statements, or the “Scroll to continue” link is displayed but no “Continue” button is there.

See [[Unexpected installation halts]] for more about solutions that involve:
*Checking for MySQL limits
*Checking the .htaccess files
*Code customizations issues
*Checking memory limit
*Upgrade incrementally
*Fix fopen function

[[#top|Top]]

==Why can't I upload a new image into my profile?==

If you don't see anything on your user profile pages to let you upload user images then it's usually one of the following:
*The permissions associated with the role you are using are preventing you from changing your profile picture.
* GD is not installed, or is not enabled on your server. Make sure '''GD has been included in your PHP installation'''. You can check this by going to ''Site Administration > Server > PHP info'' and looking for the gdversion setting. This setting is chosen automatically every time you visit that page. If it shows GD version 1 or version 2 then everything should be fine. Save that configuration page and go back to your user profile.
* GD is installed, but is in some way corrupt. For instance, [http://moodle.org/mod/forum/discuss.php?d=44271#p386194 see this discussion on empty lines or white spaces in config files.]
GD is a library that allows image processing. For example, when all is well with your system, and you upload a new profile image, GD compresses the image and produces two thumbnails, one is 100x100 pixels, and the other is 35x35 pixels.

If Moodle thinks GD is not installed, then you will need to '''install the GD library'''.
*On Unix you may need to re-compile PHP with arguments something like this:

./configure --with-apxs=/usr/local/apache/bin/apxs --with-xml --with-gd
--with-jpeg-dir=/usr/local --with-png-dir=/usr --with-ttf --enable-gd-native-ttf
--enable-magic-quotes --with-mysql --enable-sockets --enable-track-vars
--enable-versioning --with-zlib

* On Windows this is usually a matter of "turning on" the extension in PHP by editing your php.ini file. To do this remove the semicolon for the php_gd2.dll extension - check that this file is actually present in your php extensions folder first (search your php.ini for extension_dir to determine where this points to on your hard disk). You should then have a line that looks like this:
extension=php_gd2.dll

:Windows users should see the [[Installing AMP|installation instructions]] for further help.

3. Remember to '''restart your webserver''' (if possible) and re-visit the Moodle configuration page after making any changes to PHP so it can pick up the correct version of GD.

'''See also''': Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=44271 Profile pictures] for additional information.

== Why doesn't my Moodle site display the time and date correctly? ==

Please check the timezone settings in settings in ''Administration > Site administration > Location > Location settings''.

== How do I uninstall Moodle?==

'''Webhost/manual installation''': If you have installed Moodle manually or have installed onto a webhost, follow these steps:
*Delete the moodle database using this mysql command (or delete using your mysql client, e.g. PHPMyAdmin):
<pre>sql>DROP DATABASE moodle;</pre>
:In the above example replace 'moodle' with the name of the moodle database you created when installing.
*Delete the moodledata directory. If you, or your users, have uploaded materials into this directory take a copy of these before deleting this directory.
*Delete the moodle directory itself. This will delete all of the moodle PHP script files.

'''XAMPP windows installation''': If you have installed Moodle on windows through the XAMPP package, follow these steps:
*Open cmd.exe and navigate to this directory within your installation directory:
<pre>server/mysql/bin</pre>
*Run this command, replacing USERNAME with your database username (the default is "root") and DATABASE with your database name (the default is "moodle"):
<pre>mysqladmin.exe -u USERNAME -p drop DATABASE</pre>
*Enter your database password at the prompt (the default is "" [blank]).
*Enter "y" to confirm the database drop.
*Delete the moodledata directory. If you, or your users, have uploaded materials into this directory take a copy of these before deleting this directory.
*Delete the moodle directory itself. This will delete all of the moodle PHP script files.

==Migrating Moodle to a new site or server==
Migrating Moodle means that you have to move the current installation to a new server, and so may have to change IP addresses or DNS entries. To do this you will need to change the $CFG->wwwroot value in the config.php on the new server. You will also have to change any absolute links stored in the database backup file (before restoring the file on the new server) either using the [[Search and replace tool]], your text editor or another "search and replace" tool, e.g. sed. For more details see the [[Moodle_migration | Moodle Migration]] page.

[[#top|Top]]

==Why does my new installation display correctly on the server, but when I view it from a different machine, styles and images are missing?==
In the installation instructions, one of the suggested settings for 'webroot' is 'localhost'. This is fine if all you want to do is some local testing of your new Moodle installation. If, however, you want to view your new installation from another machine on the same local area network, or view your site on the internet, you will have to change this setting:
*For local testing, 'localhost' is fine for the webroot ($CFG->wwwroot in config.php).
*If you want to test your site from other machines on the same local area network (LAN), then you will have to use the private ip address of the serving machine, (e.g. 192.168.1.2/moodle) or the network name of the serving computer (e.g. network_name_of_serving_machine/moodle) as the web root. Depending on your LAN setup, it may be better to use the network name of the computer rather than its (private) ip address, because the ip address can and will change from time to time. If you don't want to use the network name, then you will have to speak to your network administrator and have them assign a permanent ip address to the serving machine.
*Finally, if you want to test your new installation across the internet, you will have to use either a domain name or a permanent (public) ip address/moodle as your web root. To handle both types of access, see [https://docs.moodle.org/en/masquerading masquerading].

[[#top|Top]]
==Maximum upload file size - how to change it?==
There are several places to change the maximum file upload size. The first place to check is in Site administration > Security > Site security settings and look for "Maximum uploaded file size". This is the "maxbyte" variable found in older versions of Moodle (under Admin > Variables). Teachers may also set the maximum file size by the [[Course_settings#Maximum_upload_size|course administration block]].

If the above does not provide a large enough figure you will need to make changes in your server settings. The usual place is in your php.ini file (go to Site administration > Server > PHPinfo and check a few lines down for its location). Look for settings '''upload_max_filesize''' and '''post_max_size''', setting them both to your desired new value (e.g. '64MB'). You will need to restart the web server for these changes to take effect - e.g. on Linux, '''/etc/init.d/apache2 force-reload'''. Check your documentation or just reboot the server. [http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size NGINX] system administrators should also add client_max_body_size=XXX to the "http" section of their nginx main configuration file. ([https://rtcamp.com/tutorials/php/increase-file-upload-size-limit/#change-in-nginx-config see more info])

For more help see:
*[[Administration_FAQ#How_do_the_limits_on_uploaded_files_work.3F]]
*[[Installing_Moodle#Recheck_PHP_settings]]
*[[Installing_Moodle#Using_a_.htaccess_file_for_webserver_and_PHP_settings]]
*[[Site_policies#Maximum_uploaded_file_size]]
*These forum posts: http://moodle.org/mod/forum/discuss.php?d=63840#287960 and http://moodle.org/mod/forum/discuss.php?d=93882#p414650

[[#top|Top]]

==Moodle claims PHP float handling is not compatible==

The symptom is that when you try to install or upgrade your Moodle, you get a message "Detected unexpected problem in handling of PHP float numbers".

[http://moodle.org/mod/forum/discuss.php?d=114945 This forum thread] and MDL-18253 have more information. In short, this problem should not happen, you can help us by telling posting information about exactly which version of PHP, and OS you are using. That may let us find a way to work around this problem.

You may be able to solve this issue by installing a more recent PHP versions. If you compile PHP yourself from source, changing the compilation options may help. However, since we don't understand the cause, we don't really know. If you do find a solution that works for you, please do tell us about it.

Update: we have a guess that the problem may be the [http://au2.php.net/manual/en/ini.core.php#ini.precision 'precision' setting in your php.ini file]. In a default PHP install this is set of 14. On at least one server that exhibited this problem it had been changed to a smaller value. So, if you see this problem, please try adding
ini_set('precision', 14);
to your config.php file, and report your success in MDL-18253.

== How do I run multiple instances of Moodle without duplicating base code? ==

See [http://moodle.org/mod/forum/discuss.php?d=13211 this thread] for a detailed explanation by [[User:Martin_Langhoff| Martin Langhoff]].

== How do I install a plugin? ==

Please see [[Installing plugins]].

==I can't enable a plugin on the Plugins overview page because the icon is not clickable==
The open and closed eye icon on the Plugins overview page is simply there to show whether or not a plugin is enabled. You can't edit plugins from this screen. If you wish to enable a plugin, go to the appropriate page for managing the type of plugin you need, for instance ''Settings>Site administration>Plugins>Repositories>Manage repositories'' or ''Settings>Site administration>Plugins>Activity modules>Manage activities.''

== See also ==

* [[Errors FAQ]]
* [http://moodle.org/mod/forum/view.php?id=28 Installing and upgrading help forum] on moodle.org

Installing Moodle in a shared web hosting environment:
* [[Finding_and_Selecting_A_Web_Host|Finding and Selecting a web host]]

[[Category:FAQ]]

[[es:FAQ Instalación]]
[[fr:FAQ d'installation]]
[[ja:インストールFAQ]]
[[de:Installation FAQ]]

Development:Question Engine 2:How the question engine currently works

2021-07-14T13:24:33Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Template:Question_engine_2}}
This page gives and overview of how the question engine works in Moodle 1.9, and some of the problems inherent in that.

Previous section: [[Development:Question Engine 2:Rationale|Rationale]]

==How this part of the quiz currently works==

Before saying what I would like to change, I think it is best to summarise how the question engine currently works.

===Database tables===

There are three database tables that store data about students' attempts at questions.

====question_attempts====

This table is basically used to generate unique ids for the other tables relating to question attempts, and allow one to link the data in those tables to the other parts of Moodle that use the question bank, for example from a quiz attempt.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id used to link attempt question data to other things, e.g. quiz_attempts.uniqueid
|-
| modulename || NOT NULL VARCHAR(20) || e.g. 'quiz' the thing linked to.
|}

====question_sessions====

There is one row in this table for each question in an attempt.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id. Not used much.
|-
| attemptid || INT(10) NOT NULL REFERENCES question_attempts.id || Which attempt this data belongs to.
|-
| questionid || INT(10) NOT NULL REFERENCES question.id || Which question this is the attempt data for.
|-
| newest || INT(10) NOT NULL REFERENCES question_states.id || The latest state of this question in this attempt.
|-
| newgraded || INT(10) NOT NULL REFERENCES question_states.id || The latest graded state of this question in this attempt.
|-
| sumpenalty || NUMBER(12,7) NOT NULL || Used for adaptive mode scoring.
|-
| manualcomment || TEXT || A teacher's manual comment.
|}

(attemptid, questionid) is an alternate key, but that makes MDL-15596 impossible to satisfy.

====question_states====

There are several rows here for each question session, recording the different states that the question went through as the student attempted it. For example open, save, submit, manual_grade.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id. Not used much.
|-
| attempt || INT(10) NOT NULL REFERENCES question_attempts.id || Which attempt this data belongs to.
|-
| question || INT(10) NOT NULL REFERENCES question.id || Which question this is the attempt data for.
|-
| seq_number || INT(10) NOT NULL || Numbers the states within this question attempt.
|-
| answer || TEXT NOT NULL || A representation of the student's response.
|-
| timestamp || INT(10) NOT NULL || Timestamp of the event that lead to this state.
|-
| event || INT(4) NOT NULL || The type of state this is. One of the QUESTION_EVENTXXX constants from the top of questionlib.php.
|-
| grade || NUMBER(12,7) NOT NULL || The grade that had been earned by this point, after penalties had been taken into account.
|-
| raw_grade || NUMBER(12,7) NOT NULL || The grade that had been earned by this point, before penalties had been taken into account.
|-
| penalty || NUMBER(12,7) NOT NULL || Used by the adaptive mode scoring.
|}

(attempt, question, seq_number) is an alternate key (see the remark in the previous sub-section).

The student's response is stored in the answer column. It is up to each question type to convert the data received from the student into a single string in whatever format seems best, even though the response come from a HTTP post, and so is just an array of key => value pairs, which could easily be stored directly in the database without each question type having to write some nasty string concatenation/parsing code.

===Code flow===

A part of Moodle, for example the Quiz module, wishes to use questions. First, mod/quiz/attempt.php will render a page of questions by calling
# load_questions,
# load_question_states, and
# print_question one or more times.
All three of these functions delegate part of the work to the appropriate question type.

This outputs each question in its current state. Any form controls that are output have a name="" attribute that is a combination of a prefix determined by the question engine (e.q. q123_), and a main part determined by the question type.

When this page is submitted, the response goes to whichever script the question using code designate. In the case of the quiz it is mod/quiz/processattemptattempt.php. This calls
# load_questions,
# load_question_states,
# question_extract_responses,
# question_process_responses, and
# save_question_state.
# In the case of the quiz, it then saves the quiz_attempts row, which has been updated by some of the above methods.
Again, steps 1., 2., 4. and 5. delegate part of the work to the question types.

Processing manual grading by the teacher is similar. The sequence of calls is:
# load_questions,
# load_question_states,
# question_process_comment, and
# save_question_state.
# In the case of the quiz, it then saves the quiz_attempts row, which has been updated by some of the above methods.

One thing to note here is that a lot of processing is done before any data can be stored in the database.

Another point to note is that the question type classes are singleton classes. That is, only one instance of each question type is created. All the methods used by the question engine are passed a $question and possibly a $state object to tell the question type which question instance they should be processing. This is good design from several points of view. It works well with batch database queries (efficiency) and the question types to not have state, which might become inconsistent (robustness). However, there is a slight price here, since very rich question types cannot cache state in memory, so they may have to repeat processing (richness <-> efficiency trade off) however, they can store state in the database since they can put whatever they like in the question_states.answer field.

==See also==

In the next section, [[Development:Question Engine 2:Overview|Overview]], I give the broad outline of how I think this should work in future.

* Back to [[Development:Question_Engine_2|Question Engine 2]]

Filters used on the Moodle.org forums

2021-07-14T13:24:33Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Filters}}
The [http://moodle.org/mod/forum/index.php?id=5 Moodle.org forums] have a number of [[Filters|filters]] to make it easier to talk about Moodle. This page lists them.

==Standard filters==

* [[Email protection filter|Email protection]]
* [[Display emoticons as images filter|Display emoticons as images]]
* [[Convert URLs into links filter|Convert URLs into links]]
* [[Glossary auto-linking filter|Glossary auto-linking]] - Automatically links to things defined in the [http://moodle.org/mod/glossary/view.php?id=851 Glossary of common terms] when the term is mentioned.
*[[Multi language content]]
*[[Multimedia plugins]] (with default settings i.e. all media format filters except .swf are enabled).
*[[MathJax filter|MathJax]]

Filters which are off, but available
* [[Activity names auto-linking filter|Activity names auto-linking]]
* [[Database auto-linking filter|Database auto-linking]]

==Contributed filters==

===Tracker issue auto-linking===

Automatically links to [http://tracker.moodle.org/ tracker] issues when you type the issue number e.g. MDL-1234.

===Moodle Docs auto-linking===

Automatically links to a page in the user documentation wiki (most recent version) when you type the page title enclosed in double square brackets.

For example, to link to https://docs.moodle.org/en/Philosophy type
<nowiki>[[Philosophy]]</nowiki>

To link to a page in the developer docs, add an extra pipe "|" divider followed by dev.

For example, to link to https://docs.moodle.org/dev/Plugins type
<nowiki>[[Plugins||dev]]</nowiki>
or
<nowiki>[[Plugins|Plugins developer documentation|dev]]</nowiki>

To link to a page in a documentation wiki in another language, add an extra pipe "|" divider followed by the language code.

For example, to link to https://docs.moodle.org/es/Los_10_mitos_de_Moodle type
<nowiki>[[Los 10 mitos de Moodle||es]]</nowiki>
or
<nowiki>[[Los 10 mitos de Moodle|Top 10 Moodle Myths in Spanish|es]]</nowiki>

===Auto-linking phrases===

{| class="wikitable"
|-
! Phrase
! Link
|-
| Moodle Roadmap
| https://docs.moodle.org/dev/Roadmap
|-
| Moodle Themes
| http://moodle.org/themes
|-
| Moodle Tracker
| http://tracker.moodle.org/
|-
| Moodle jobs
| http://moodle.org/jobs
|-
| Moodle books
| http://moodle.org/books
|-
| Plugins directory
| http://moodle.org/plugins/
|}

===More contrib filters===

*[[Code syntax highlighting]]

[[Category:Moodle.org]]

[[ja:Moodle.orgフォーラムで使用されているフィルタ]]

Development:Question Engine 2:Design

2021-07-14T13:24:32Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Template:Question_engine_2}}
This page explains how I think the question engine should work in Moodle 2.0 or 2.1.

Previous section: [[Development:Question Engine 2:Overview|Overview]]

{{Work in progress}}

==Words related to grades==

Within the quiz/question engine system we have to deal with three different types of grade/score/mark/whatever.

For any activity, say a quiz, it will eventually calculate a grade that is passed to the gradebook. For example, the quiz grade may be out of 100.

Within the quiz, there will be a number of questions. Let us suppose there are 6 questions each worth 3 marks, and 1 question worth 2 marks. Therefore, the quiz is out of 20 marks, and the student's mark is multiplied by 5 to get a grade out of 100 that is sent to the gradebook.

Finally, at the lowest level of the quiz, grades are stored on a scale of 0..1. We call this a fraction. So the student's mark for a question is their fraction, multiplied by the maxmark for the question. We do this so that it is easy to do things like change how many marks a question is worth within a quiz.

Therefore, we have the three words fraction, mark and grade that should be used consistently throughout the question engine code. Fractions are rarely shown in the user interface*, while I believe the quiz UI already uses the marks/grades terminology consistently.

When used as a verb - to assign a grade/mark/fraction - as in grade_response, regrade or manual_grade, the work grade is always used.

<nowiki>*</nowiki> the one place where fraction is displayed in the UI is on the question editing screens, where you set the 'grade' for a particular answer on a scale of 0 to 100%.

==New database structure==

[[Image:Question engine 2 database.png]]

===question_usages===

This is a rename of question_attempts.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id used to link attempt question data to other things, for example a quiz_attempt.
|-
| contextid || INT(10) NOT NULL || The context that this question attempt is associated with. For example the quiz context.
|-
| owningplugin || NOT NULL VARCHAR(255) || The plugin this attempt belongs to, e.g. 'mod_quiz', 'block_questionoftheday', 'filter_embedquestion'.
|-
| preferredbehaviour || NOT NULL VARCHAR(255) || The the archetypal behaviour that should be used for new questions added to this usage.
|}

===question_attempts===

This replaces question_sessions. Question sessions is not a great name because session has other connotations in the context of web applications. I think it is right to use the question_attempt name here, because this tables has one row for each attempt at each question.

There is now no requirement for (attemptid, questionid) to be unique.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id. Linked to from question_states.attemptid.
|-
| questionusageid || INT(10) NOT NULL REFERENCES question_usages.id || Which attempt this data belongs to.
|-
| slot || INT(10) NOT NULL || As questions are added to a usage, they are numbered sequentially.
|-
| behaviour || VARCHAR(32) NOT NULL || The question behaviour that is managing this question attempt.
|-
| questionid || INT(10) NOT NULL REFERENCES question.id || Which question this is the attempt data for.
|-
| maxmark || NUMBER(12,7) NOT NULL || The grade this question is marked out of in this attempt.
|-
| minfraction || NUMBER(12,7) NOT NULL DEFAULT 0 || Some questions can award negative marks. This indicates the most negative mark that can be awarded, on the faction scale where the maximum positive mark is 1.
|-
| flagged || INT(1) NOT NULL DEFAULT 0 || Whether this question has been flagged within the attempt.
|-
| questionsummary || TEXT || If this question uses randomisation, it should set this field to summarise what random version the student actually saw. This is a human-readable textual summary of the student's response which might, for example, be used in a report.
|-
| rightanswer || TEXT || This is a human-readable textual summary of the right answer to this question. Might be used, for example on the quiz preview, to help people who are testing the question. Or might be used in reports.
|-
| responsesummary || TEXT || This is a textual summary of the student's response (basically what you would expect to in the Quiz responses report).
|-
| timemodified || INT(10) NOT NULL || The time this record was last changed.
|}

* Need to store maxmark because it could come from anywhere, (e.g. quiz_question_instances, question.defaultgrade, ...). We need it available at various times (e.g. when displaying a question) so it is better to store it explicitly here.

===question_attempt_step===

Same purpose as the old question_states table, but simplified.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id. Linked to from question_states.stateid.
|-
| questionattemptid || INT(10) NOT NULL REFERENCES question_attempts.id || Which question attempt this data belongs to.
|-
| sequencenumber || INT(4) NOT NULL || Numbers the steps in a question attempt sequentially.
|-
| state || INT(4) NOT NULL || The type of state this is. One of the constants defined by the question_state class.
|-
| fraction || NUMBER(12,7) || The grade the student has earned for this question, on a scale of 0..1. Needs to be multiplied by question_attempts.maxgrade to get the true grade.
|-
| timecreated || INT(10) NOT NULL || Time-stamp of the event that lead to this state.
|-
| userid || INT(10) NOT NULL || The user who created this state. For states created during the attempt, this would be the student id. For a state for adding a comment or manually grading, this would be the teacher id.
|}

* We store grade unscaled (as a value between 0.0 and 1.0) because that makes regrading easier. (You might think that you can adjust scaled grades later, and that is almost true, but if maxgrade used to be 0, then you can't change it to anything else.)

===question_attempt_step_data===

This stores the data submitted by the student (a list of name => value pairs) that lead to the state stateid. This replaces the old question_states.answer field.

There will be a convention that ordinary names like 'myvariable' should be used for submitted data belonging to the question type; names prefixed with a :, like ':myaction' should be used for data belonging to the question behaviour; and names prefixed with a _ can be used for internal things, for example, the random question might store '_realquestionid' attached to the 'open' state, or a question type that does a lot of expensive processing might store a '_cachedresult' value, so the expensive calculation does not need to be repeated when reviewing the attempt.

Note that, the old question_states.answer field used to save a lot of repetitive information from one state to the next, for example the other questionid for random questions, and the choices order for multiple-choice questions with shuffle-answers on. In future, this sort of repetitive information will not be saved. Instead, during question processing, the question types will be given access to the full state history.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) NOT NULL AUTO INCREMENT || Unique id. Not used much.
|-
| attemptstepid || INT(10) NOT NULL REFERENCES question_attempt_steps.id || Which state the submission of this data lead to.
|-
| name || VARCHAR(32) NOT NULL || The name of the parameter received from the student.
|-
| value || TEXT || The value of the parameter.
|}

==Upgrading the database==

TODO

==New list of states that a question may be in==

The aim here is to have as few states as necessary. What is necessary? To make it clear what is going on, for example in the quiz navigation. Of course, that is only one case to consider.

; Incomplete
: This is the state that questions start in. They stay in this state as long as the student still needs to give this question attention. In deferred feedback (non-adaptive) mode, that is until the student has entered an answer. (For a short-answer question, any answer in the input box moves you out of this state; for a matching question, you only move out of this state when you have answered all the sub-questions.) In adaptive mode, the question stays in this state until either you have got it right, or you have run out of tries.
: In the state, the student can enter or change their answer.
; Complete
: This state is for questions where the student have done enough, but the attempt is still open, so they could change their answer if they wanted to. For example, this happens in deferred feedback mode when the student has entered a complete answer, and before they do submit all and finish. Also, a Description, after the student has seen it.
: In the state, the student can enter or change their answer.
; Graded(Correct/PartiallyCorrect/Incorrect)
: For computer-graded questions, once the student can no longer interact with the question, it goes to one of the sub-states of the graded state.
; Finished
: For questions that do not have a grade, for example descriptions, after the attempt is over, they go into this state.
; GaveUp
: This state is used for questions where it is impossible to assign a grade because the student did submit all and finish when the question was in the incomplete state. However, this does not necessarily happen, for example, we may choose to grade an incomplete matching question if the student has completed at least one sub-question.
; ManuallyGraded(Correct/PartiallyCorrect/Incorrect)
; Commented
; GaveUpCommented
: These three states correspond the the previous three states after the teacher has added a comment and/or manually graded.

[[Image:Question_state_diagram.png]]

==API for modules using the question engine==

Here is some proposed code from an integration test method. It creates an attempt containing one true/false question and walks through a student getting it right, and then at teacher overriding the grade.

<code php>
public function test_delayed_feedback_truefalse() {
// Create a true-false question with correct answer true.
$tf = $this->make_a_truefalse_question();
$displayoptions = new question_display_options();

// Start a delayed feedback attempt and add the question to it.
$tf->maxgrade = 2;
$quba = question_engine::make_questions_usage_by_activity('unit_test');
$quba->set_preferred_behaviour('delayedfeedback');
$qnumber = $quba->add_question($tf);
// Different from $tf->id since the same question may be used twice in
// the same attempt.

// Verify.
$this->assertEqual($qnumber, 1);
$this->assertEqual($quba->question_count(), 1);
$this->assertEqual($quba->get_question_state($qnumber), question_state::NOT_STARTED);

// Begin the attempt. Creates an initial state for each question.
$quba->start_all_questions();

// Output the question in the initial state.
$html = $quba->render_question($qnumber, $displayoptions);

// Verify.
$this->assertEqual($quba->get_question_state($qnumber), question_state::INCOMPLETE);
$this->assertNull($quba->get_question_grade($qnumber));
$this->assertPattern('/' . preg_quote($tf->questiontext) . '/', $html);

// Simulate some data submitted by the student.
$prefix = $quba->get_field_prefix($qnumber);
$answername = $prefix . 'true';
$getdata = array(
$answername => 1,
'irrelevant' => 'should be ignored',
);
$submitteddata = $quba->extract_responses($qnumber, $getdata);

// Verify.
$this->assertEqual(array('true' => 1), $submitteddata);

// Process the data extracted for this question.
$quba->process_action($qnumber, $submitteddata);
$html = $quba->render_question($qnumber, $displayoptions);

// Verify.
$this->assertEqual($quba->get_question_state($qnumber), question_state::COMPLETE);
$this->assertNull($quba->get_question_grade($qnumber));
$this->assert(new ContainsTagWithAttributes('input',
array('name' => $answername, 'value' => 1)), $html);
$this->assertNoPattern('/class=\"correctness/', $html);

// Finish the attempt.
$quba->finish_all_questions();
$html = $quba->render_question($qnumber, $displayoptions);

// Verify.
$this->assertEqual($quba->get_question_state($qnumber), question_state::GRADED_CORRECT);
$this->assertEqual($quba->get_question_grade($qnumber), 2);
$this->assertPattern(
'/' . preg_quote(get_string('correct', 'question')) . '/',
$html);

// Process a manual comment.
$quba->manual_grade($qnumber, 1, 'Not good enough!');
$html = $quba->render_question($qnumber, $displayoptions);

// Verify.
$this->assertEqual($quba->get_question_state($qnumber), question_state::MANUALLY_GRADED_PARTCORRECT);
$this->assertEqual($quba->get_question_grade($qnumber), 1);
$this->assertPattern('/' . preg_quote('Not good enough!') . '/', $html);
}
</code>

Note that this code does not interact with the database at all. Data is only stored to or loaded from the database if you call $qag->load_... or $qag_save... methods.

==New classes==

===question_engine===

This is a static factory class that provides an entry point to all the other question engine classes.

===question_state===

An enumeration that defines constants the various states a question can be in, with some helper methods:

<code php>
abstract class question_state {
const NOT_STARTED = -1;
const UNPROCESSED = 0;
const INCOMPLETE = 1;
const COMPLETE = 2;
const NEEDS_GRADING = 16;
const FINISHED = 17;
const GAVE_UP = 18;
const GRADED_INCORRECT = 24;
const GRADED_PARTCORRECT = 25;
const GRADED_CORRECT = 26;
const FINISHED_COMMENTED = 49;
const GAVE_UP_COMMENTED = 50;
const MANUALLY_GRADED_INCORRECT = 56;
const MANUALLY_GRADED_PARTCORRECT = 57;
const MANUALLY_GRADED_CORRECT = 58;

public static function is_active($state) { ... }
public static function is_finished($state) { ... }
// ...
}
</code>

===question_display_option===

This class contains all the options for what may, or may not, be visible when a question is rendered.

<code php>
class question_display_options {
public $flags = QUESTION_FLAGSSHOWN;
public $readonly = false;
public $feedback = false;
// ...
}
</code>

===question_definition===

This class encapsulates the question definition. This used to be passed round in $question stdClass objects. Now we have a real class.

There will be subclasses like
* question_truefalse
* question_multichoice
* ...

I think some behaviour (e.g. grade_responses, get_renderer) will be in this class.

===question_usage_by_activity===

Related to the question_usages table in the DB.

This is the main class that activity modules will use. For example, there might be a question_usage_by_activity for a quiz attempt or a lesson attempt.

There are methods to add questions to the attempt, start and finish the attempt, and submit data to a particular question.

===question_attempt===

Related to the question_attempts table in the DB.

Stores all the information about the student's attempt at one particular question as part of a question_usage_by_activity.

===question_attempt_step===

Related to the question_attempts_step and question_attempts_data table in the DB.

A question_attempt comprises a sequence of steps. Each step has an associative array of submission data, that is, principally the data that was submitted in the HTTP request that created the new step.

Each step also has a state. That is, one of the question_state constants, and optionally a grade.

There are two helper classes question_attempt_step_iterator and question_attempt_reverse_step_iterator which let you write code like
<code php>
foreach ($qa->get_iterator() as $stepindex => $step) {
// Do something with each step of the question attempt in order.
}
</code>

===question_behaviour===

Will have subclasses like
* qbehaviour_delayedfeedback
* qbehaviour_interactive
* ...

Question behaviours control exactly what happens when as a question_attempt is started, a submission is processed, or finished, etc.

===core_question_renderer===

Renderers are responsible for generating the HTML to display a question in a particular state. The core_question_renderer it responsible for all the bits that do not depend on the current question type or behaviour.

===qtype_renderer===

Base class for
* qtype_truefalse_renderer
* qtype_multichoice_renderer - and possibly also qtype_multichoice_horizontal_renderer
* ...

Responsible for generating the bits of HTML that depend on the question type. For example the question text, and input elements.

===qbehaviour_renderer===

Base class for
* qbehaviour_delayedfeedback_renderer
* qbehaviour _interactive_renderer
* ...

Responsible for generating the bits of HTML that depend on the behaviour. For example the submit button in adaptive mode.

==Changes to the question type API==

Can this be backwards compatible? It is looking like it will be better to break backwards compatibility - or at least to introduce new API methods. It may prove possible to keep old question types mostly working by providing implementations of the new API in terms of the old API methods.

==Proposed robustness and performance testing system==

A major change to the question engine should really only be contemplated in combination with the introduction of a test harness that makes it easy to run correctness, performance and reliability tests.

One advantage of the way data will be stored in the new system is that everything originally submitted by the user will be stored in the database in a format very close to the one in which it was originally received by the web server. Therefore, it should be easy to write a script that replays saved quiz attempts. This is the basis of a test harness. I will create such a test script as part of this work.

==Huge class diagram==

This diagram shows all the classes in the question code (no including specific plugins), with most of the core of my new proposal implemented.

[[Image:Question_classes.png]]

==See also==

In the next section, [[Development:Overview_of_the_Moodle_question_engine|Overview_of_the_Moodle_question_engine]] summarises the new system. It is intended to be the developer documentation for the new system once it is finished.

* Back to [[Development:Question_Engine_2|Question Engine 2]]

report/myfeedback/index

2021-07-14T13:24:31Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

=Moodle My Feedback=
When installed, the Moodle My Feedback report appears in the My Profile > Activity Reports menu and allows students to see an overview of all their grades and feedback for assessment activities such as Moodle Assignments, Turnitin Assignments (v1 & v2), Workshops and Quizzes. It provides their visible grades and a link to their submission and any feedback that has been released to them.

The report can be accessed via the user profile (Activity Reports > My Feedback report). Access is controlled by the user context, teacher will be able to see this user's grades for the courses that they are teacher in Users can only see their own grades Admin and manager can see all grades for all users (unless permissions prohibit this)

The report is intended to help students understand the variety of feedback they receive. It can also be used to identify similarities between feedback received from across modules and years to help students see how they can improve their work in future assessments.]

==What is My Feedback?==
My Feedback is a single-view report that enables different staff and student roles to view a report of grades and feedback recorded in Moodle, across modules. The report includes Moodle Assignments, Turnitin Assignments, Workshops, Quizzes and Grade items entered directly in the Moodle course Gradebook.
The report provides links to submissions and any feedback that has been released to students.
Watch the video on how students can use the My Feedback report:

{{MediaPlayer | url = https://www.youtube.com/watch?v=gI9Mq4qsFPs}}

==Installation==

The plugin is available for download from: https://moodle.org/plugins/view.php?plugin=report_MyFeedback and the installation guide is available at: https://docs.moodle.org/33/en/report/myfeedback/install

==Who can use it?==
When installed and enabled, My Feedback is available to students, personal tutors, teachers and departmental administrators.

Students can view feedback and grades from their assessments across all their UCL Moodle courses.
* Personal tutors can see their tutees' full My Feedback reports across all the modules their students are studying. Note: personal tutors will not be able to link through to assessments on courses they do not have tutor access to. Personal tutors are assigned to students using the Moodle Parent role functionality.
* Teachers can see M yFeedback reports for their students containing assessment information for any modules they teach and/or assess. They will not see any assessments for modules they do not teach (unless they have been granted teacher access to those Moodle courses).
* Departmental administrators can see My Feedback reports for all the Moodle courses within categories where they have been assigned departmental administrator access in Moodle. Categories in Moodle will either be for the entire department, or might be broken down further into undergraduate and postgraduate modules. This feature assumes your Moodle installation makes use of category enrolments.

==How can staff give feedback that is visible in the report?==
To make the most of My Feedback, teachers and markers need to use Moodle in ways that makes the information visible within the report. Many of these suggestions also make assessment feedback more visible to students generally.
Note: If deciding between Moodle Assignments and Turnitin Assignment, be aware that Turnitin feedback cannot be shown directly in the My Feedback report and requires the student to copy and paste this in, so Moodle Assignment feedback is more visible in the report.

Below are some tips for how to make feedback visible within each type of assessment
shown within the report.

===Moodle Assignments===
- Grades must be entered in the grade box (as opposed to being embedded within a document, or the feedback comments area). Otherwise it won't be shown in the grade column in the report. Moodle Assignments support numeric, letter and scale grades.
- General feedback should be entered into the feedback comments area, rather than embedded in a document, as only feedback added in this box will be visible within the 'feedback comments' section of the report.
- Rubric or marking guide comments should be entered directly into the Advanced Grading section of the Moodle Assignment (rather than being attached in a separate document) in order for this feedback to display in the 'feedback comments' section of the report.
- If you provide inline comments / tracked changes within the paper via feedback files, tell students this in the feedback comments, so they know to look for it.
- Students who are granted extensions need to have this set up within the Assignment's 'view submissions' page, otherwise their submission will display in the report as late.

===Turnitin Assignments===
 Grades must be entered in the grade (/100) area (in the top, right corner) in order to appear
in the grade column of the report. That means if you are using letter grades written directly
into the general comments area, these will not show in the report and will only be visible to
students when they click through to the Turnitin assignment via the 'view feedback' link.
 All other feedback (inline 'QuickMark' comments, general 'text comments' and
'rubrics'/'grading forms') will only be visible to students when they click on the 'view
feedback' link. If they want to see any of this directly in the 'feedback comments' section of
the report, they will need to copy and paste this in manually.

===Quizzes===
 Provide overall feedback in the quiz settings, that points students to reviewing each quiz
question for detailed feedback relating to that question. You can provide feedback within
certain grade boundaries by adding more feedback fields and entering the percentages in
the grade boundary boxes. E.g. If they pass the quiz with a high score you might want to add
some positive comments and if they fail the quiz, point them to further readings or
resources.
 Provide detailed feedback for each quiz question in the general feedback section, rather
than the incorrect or correct sections, as someone who got a question right may not fully
understand why and may want to review this.
 Students who are granted extensions for quizzes with a deadline need to have this set up
within the group or user overrides section of the quiz, otherwise their attempt will display in
the report as late.

===Workshops===
 Provide overall feedback for the group in the Workshop settings, under Feedback, in
the conclusion area. This will appear for all students in the 'feedback comments' section of
the report.

===Manual grade items===
 If you add grades directly to the Moodle Gradebook (for example to provide feedback for an oral presentation) you should ideally upload a single grade for the entire assessment, rather
than uploading a grade for each criterion. Uploading a separate grade for each criterion will
result in students having to sift through many grade entries for a single assessment.

===Grades entered directly in Gradebook===
 Grades that are entered or overridden directly in the Moodle Gradebook for an existing activity, will appear in the report, overwriting the grade within the assignment, workshop or quiz.

==How do I access and use the report?==
The Moodle My Feedback report can be accessed from the My Profile > Activity Reports menu. You can access your profile by clicking on your name, in the top, right corner of Moodle.

If you are both a student and a teacher, you can view your own report as well as the reports of those you teach.

[[Image:3. MyFeedbackLinkfromProfile.png|800px|center|My Feedback link from Moodle Profile|link=https://docs.moodle.org/31/en/images_en/a/a9/3._MyFeedbackLinkfromProfile.png]]

===Overview tab===
The '''overview tab''' lists all feedback and/or grades a student has received from any Moodle Assignments, Turnitin Assignments, Workshops and Quizzes within a particular academic year.
As seen in the screenshot below, the My Feedback report table can be filtered, exported to excel and the current view printed.
However, please note that assessments without a grade or feedback will neither be displayed on the dashboard nor the exported excel report.
The assessment table shown lists the following:
* Module that the assessment belongs to
* Name of the assessment
* Assessment type
* Assessment due date
* Submission date
* Full feedback (a link is provided, which presents the Student's submitted assessment with feedback attached)
* Assessment grade
* Range (the number of marks available for the assessment)
* A bar graph indicating how close the Student was to achieving the highest mark for the assessment

[[File:1.My_feedback_v2.7_overview.png|800px|center|My Feedback overview tab|link=https://docs.moodle.org/31/en/images_en/3/3f/1.My_feedback_v2.7_overview.png]]

===Feedback Comments tab===
The Feedback comments tab shows general feedback* from a student's Module Tutors for each assessment, as well as selected grading rubric levels and marking guide comments from Moodle Assignments.
Overall feedback from Moodle quizzes is also provided. In depth quiz feedback will usually be found within the attempt alongside each question. To see this click the 'View last attempt' link in the Full Feedback column. For other assessment types click the 'View feedback' link in the Full Feedback column to see contextualised feedback for the assessment. E.g. the level you obtained alongside other grading levels within a rubric, in text comments added directly to your assessment etc.

Students can add self-reflective notes against your graded assessments, which can be viewed by your Personal Tutor and Departmental Administrator.

The date students viewed the feedback from an assessment is also displayed, allowing tutors to easily determine whether their comments are being read. Feedback that has not been viewed by the student will have a cross displayed beside it.

*If the assessment is a Turnitin assignment, general feedback cannot be displayed automatically, however you can copy and paste comments from the original feedback provided on your Turnitin assignment if you would find it useful to view this feedback alongside other assessments.

[[File:Moodle31-MyFeedback-FeedbackComments.PNG|800px|center|My Feedback Feedback Comments tab|link=https://docs.moodle.org/31/en/images_en/9/97/Moodle31-MyFeedback-FeedbackComments.PNG]]

===Personal Tutor tab===
The Personal tutor tab holds the contact information for the Personal Tutor assigned to a Student.

===My students tab ===
This tab is visible to anyone who is a teacher on a Moodle course, who has been assigned as a Personal Tutor to a student using Moodle parent roles, or who has departmental administrator access to My Feedback.

The My students tab lists all of the student's linked to the modules assigned to a teacher. You will need to click the 'Show all students checkbox' to see the students you teach. By default only those students you are a Personal Tutor for will display. You can search for a student by name in the Search box.
Assessment information for a particular student can be viewed by clicking on the student's name.

[[Image:MyStudents.PNG|800px|center|My Feedback My students tab|link=https://docs.moodle.org/31/en/images_en/9/9b/MyStudents.PNG]]

===Personal Tutor dashboard===

The Personal Tutor dashboard is visible to anyone who has been granted the Personal Tutor parent role to one or more students in Moodle.

The Personal tutor dashboard displays all of a students assigned to a personal tutor. From this screen, personal tutors are able to send multiple (blind) emails to their tutees.
The summary table shown in the image above lists the following:
Personal tutee/ module names
The number of assessments submitted by the tutee for the module (to date)
The number of non-submissions by the tutee
The number of late submissions by the tutee
The number of graded assessments for the tutee
The number of assessments that the tutee has received low grades for (less than 50%) of the total mark

Clicking on a student's name will lead to their respective Overview page, providing a summary of their performance in the modules they are studying. The Feedback comments tab will also become available
Note: To return to your own My Feedback dashboard after viewing a student report, click on the View own dashboard button.

[[Image:Personal_tutor_dashboard.PNG|800px|center|My Feedback Personal Tutor Dashboard|link=https://docs.moodle.org/31/en/images_en/5/51/Personal_tutor_dashboard.PNG]]

===Module Tutor dashboard===
The Module tutor dashboard is visible to anyone who is a teacher on a moodle course.

* The Module tutor (aka Teacher) dashboard provides a breakdown of students' performance in the modules assigned to a teacher. This view can be toggled between an Assessment breakdown and a Student breakdown.
* The Assessment breakdown organises student grades according to their module of study, while the Student breakdown lists each student by name and the number of assessments they have been given.
* Teachers can gain further insight into the assessment information of individual students by clicking on the student's name. They will then see the My Feedback report for that student.

Note: To return to your own My Feedback dashboard after viewing a student report, click on the View own dashboard button.

[[File:Module tutor dashboard.PNG|800px|center|My Feedback Module Tutor Dashboard tab|link=https://docs.moodle.org/31/en/images_en/b/b1/Module_tutor_dashboard.PNG]]

===Departmental Admin Dashboard===
For those institutions using category level enrolments you may have access to the My Feedback Department Admin Dashboard.

* The Departmental admin dashboard displays assessment statistics for the courses and modules linked to a Departmental admin, depending on the course level filter selected.
* The report view can also be toggled to show statistics per assessment, module or module tutor.
* The Assessment breakdown organises student grades according to their module of study, while the Student breakdown lists each student by name and the number of assessments they have been given.
* Staff can gain further insight into the assessment information of individual students by clicking on the student's name.
* The Module tutor stats toggle allows Departmental admins to view the performance of Module tutors for each of their tutor groups.

Note: To return to your own My Feedback dashboard after viewing a student report, click on the View own dashboard button.

[[Image:Departmental_Admin_dashboard.PNG|800px|center|My Feedback Departmental Administrator Dashboard|link=https://docs.moodle.org/31/en/images_en/2/21/Departmental_Admin_dashboard.PNG]]

===Usage dashboard===
The usage reports shows how students and staff have been using the My Feedback usage reports. The data can be printed and exported to excel for further analysis.

There are a number of reports that can be run.
* Category students overview: This report shows an overview of student usage within a category.
* Category staff overview: This report shows an overview of staff usage within a category.
* Category students: This report shows a list of students and their individual usage within a category.
* Category staff: This report shows a list of staff and their individual usage within a category.
* Course students overview: This report shows an overview of student usage within each course within a particular Category.
* Course staff overview: This report shows an overview of staff usage within each course within a particular category.
* Course students: This report shows a list of students and their individual usage within a course.
* Course staff: This report shows a list of staff and their individual usage within a course.
* Student: This report shows the usage of an individual student across all their courses.
* Staff member: This report shows the usage of an individual staff member across all their courses.
* Personal tutees: This report shows an overview of a tutor\'s personal tutees and their My Feedback activity.

==Frequently Asked Questions==

===Q. Why can't students see their grades and feedback in the My Feedback report?===
A. There are a number of reasons grades and feedback might not be showing in the My Feedback report. The easiest way to check what should be seen in the report is to ask students what they see in the course gradebook (Settings block > Course Administration > Grades). The same grades should also display in My Feedback.
If the grades are not showing in the Gradebook, they will not show in My Feedback either. There are several reasons why they may not be visible:
The Moodle course has been hidden from students.
The students are no longer enrolled on the course.
The ‘Show gradebook to students’ has been set to ‘No’ in the course settings, which means the course Gradebook is hidden from students and no grades or feedback will appear for this course in the My Feedback report.
The grade item (or category it sits within) has been hidden manually, or until a certain date in the Gradebook.The Moodle course section where the assessment item is located has been hidden, or access has been restricted to particular students.
The assessment item (assignment, quiz etc.) has been hidden from students.
The grades have not yet been revealed to students (check the Turnitin Assignment post date; quiz review options; Moodle Assignment with marking workflow is set to 'released').

Additionally, Turnitin feedback cannot be seen directly in the 'Feedback comments' tab of the report unless student's copy it in manually from their Turnitin assignment.

Note: Only those with edit access to the Moodle courses in question will be able to check why the grades aren't displaying. This means if you are a personal tutor and don't have access to the Moodle courses in question you will need to speak to the teacher of the course, or to a Moodle Administrator.

===Q. How do I obtain Departmental Administrator access to the My Feedback report?===
Please speak to your Moodle Administrator about whether your institution uses Moodle category level enrolments and if so, how you can get access as a departmental administrator to the report.

==Glossary of terms used in My Feedback==
{| class="wikitable"
|-
! Term
! Definition
! Visible to
|-
| Assessment
| A set piece of assigned work or an item for which a student is given a grade and/or feedback with a Moodle course. Types of assessment are:
* Moodle assignment (including offline assignments)
* Turnitin assignment
* Workshop (for peer assessment)
* Quiz
* Manual item (grade entered into gradebook for in-class activities, such as presentations)
Staff are provided a total number of assessments a student should have submitted thus far on the Personal tutor, Module tutor and Departmental Administrator dashboards.
| Students & staff
|-
| Course
| The Moodle course that contains each assessment that appears in the My Feedback report. A course is an area in Moodle, often used to share module information, however it can also be used for other purposes (e.g to represent a programme, project, prelab activity or professional development course). The report will show the course name with a link to the course, but only those with access to the course will be able to view the course itself and the actual assessment pages it contains. Personal Tutors and Departmental Admins will see all course information in the report, but module tutors (or teachers) are restricted to only seeing courses in the report that they teach upon.
| Students and any enrolled staff
|-
| Departmental administrator
| A member of staff who has oversight for a particular department or programme in an administrative, senior teaching or management capacity (e.g. programme administrator, departmental/teaching administrator, module leader, departmental tutor, faculty tutor, programme tutor, programme director, head of department, director of studies or programme leader).
| n/a
|-
| Formative and summative assessment
| Formative assessment takes place throughout the course. It has a developmental purpose and is designed to help students to learn more effectively via set pieces of work and giving students feedback on their performance and how it can be improved and/or maintained. Formative assessment is reflective practice and does not usually contribute to the course grade at the end of the year. Any coursework that counts towards the final grade is known as 'summative' feedback.
| Staff and students
|-
| Graded assessments
| The number of assessments graded thus far, with feedback visible to students.
| Staff via dashboards
|-
| Late submissions
| The number of assignments that have been submitted after the deadline.
Note: assignment and quiz deadlines can be amended to give individuals extensions. If this is done, the report takes this into account when determining the number of late submissions. However, not all departments use this feature in Moodle, so this should kept in mind when viewing this data.
| Staff via dashboards
|-
| Low graded assessments
| The number of assessments (where the grades have been released to students) with a score below 50%.
| Staff via dashboards
|-
| Non-submissions
| The number of missed submissions for due assessments.
| Staff via dashboards
|}

[[Category:Report]]

[[es:report/myfeedback/index]]

Development:File API

2021-07-14T13:24:31Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Work in progress}}
{{Infobox Project
|name = File API
|state = Implemented
|tracker = MDL-14589
|discussion = n/a
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
}}
{{Moodle 2.0}}

==Objectives==

The goals of the new File API are:

* allow files to be stored within Moodle, as part of the content (as we do now).
* use a consistent and flexible approach for all file handling throughout Moodle.
* give modules control over which users can access a file, using capabilities and other local rules.
* make it easy to determine which parts of Moodle use which files, to simplify operations like backup and restore.
* track where files originally came from.
* avoid redundant storage, when the same file is used twice.
* fully support Unicode file names, irrespective of the capabilities of the underlying file system.

==Overview==

The File API is a set of core interfaces to allow the rest of Moodle to store, serve and manage files. It applies only to files that are part of the Moodle site's content. It is not used for internal files, such as those in the following subdirectories of dataroot: temp, lang, cache, environment, filter, search, sessions, upgradelogs, ...

The API can be subdivided into the following parts:
; File storage
: Low level file storage without access control information. Stores the content of files on disc, with metadata in associated database tables.
; File serving
: Lets users accessing a Moodle site get the files (file.php, draftfile.php, pluginfile.php, userfile.php, etc.)
:* Serve the files on request
:* with appropriate security checks
; File related user interfaces
: Provides the interface for (lib/form/file.php, filemanager.php, filepicker.php and files/index.php, draftfiles.php)
:* Form elements allowing users to select a file using the Repository API, and have it stored within Moodle.
:* UI for users to manage their files, replacing the old course files UI
; File browsing API
: Allows code to browse and optionally manipulate the file areas
:* find information about available files in each area.
:* print links to files.
:* optionally move/rename/copy/delete/etc.

== File API internals ==

=== File storage on disk ===

Files are stored in $CFG->dataroot (also known as moodledata) in the filedir subfolder.

Files are stored according to the SHA1 hash of their content. This means each file with particular contents is stored once, irrespective of how many times it is included in different places, even if it is referred to by different names. (This idea comes from the git version control system.) To relate a file on disc to a user-comprehensible path or filename, you need to use the ''files'' database table. See the next section.

Suppose a file has SHA1 hash 081371cb102fa559e81993fddc230c79205232ce. Then it will be stored in on disc as moodledata/filedir/08/13/71/081371cb102fa559e81993fddc230c79205232ce.

This means Moodle can not store two files with the same SHA1 hash, luckily it is extremely unlikely that this would ever happen. Technically it is also possible to implement reliable collision tests (with some performance cost), for now we just test file lengths in addition to SHA1 hash.

=== Files table ===

This table contains one entry for each usage of a file. Enough information is kept here so that the file can be fully identified and retrieved again if necessary. It is necessary because some databases have hard limit on index size.

If, for example, the same image is used in a user's profile, and a forum post, then there will be two rows in this table, one for each use of the file, and Moodle will treat the two as separate files, even though the file is only stored once on disc.

{| class="wikitable"
! Field
! Type
! Default
! Info
|-
| '''id'''
| int(10)
| auto-incrementing
| The unique ID for this file.
|-
| '''contenthash'''
| varchar(40)
|
| The sha1 hash of content.
|-
| '''pathnamehash'''
| varchar(40)
|
| The sha1 hash of "/contextid/component/filearea/itemid/filepath/filename.ext" - prevents file duplicates and allows fast lookup. It is necessary because some databases have hard limit on index size.
|-
| '''contextid'''
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the file.
|-
| '''component'''
| varchar(50)
|
| Like "mod_forum", "course", "mod_assignment", "backup"
|-
| '''filearea'''
| varchar(50)
|
| Like "submissions", "intro" and "content" (images and swf linked from summaries), etc.; "blogs" and "userfiles" are special case that live at the system context.
|-
| '''itemid'''
| int(10)
|
| Some plugin specific item id (eg. forum post, blog entry or assignment submission or user id for user files)
|-
| filepath
| text
|
| relative path to file from module content root, useful in Scorm and Resource mod - most of the mods do not need this
|-
| filename
| varchar(255)
|
| The full Unicode name of this file (case sensitive)
|-
| '''userid'''
| int(10)
| NULL
| Optional - general user id field - meaning depending on plugin
|-
| filesize
| int(10)
|
| size of file - bytes
|-
| mimetype
| varchar(100)
| NULL
| type of file
|-
| status
| int(10)
|
| general file status flag - will be used for lost or infected files
|-
| source
| text
|
| file source - usually url
|-
| author
| varchar(255)
|
| original author of file, used when importing from other systems
|-
| license
| varchar(255)
|
| license type, empty means site default
|-
| timecreated
| int(10)
|
| The time this file was created
|-
| timemodified
| int(10)
|
| The last time the file was last modified
|}

Indexes:
* non-unique index on (contextid, component, filearea, itemid)
* non-unique index on (contenthash)
* unique index on (pathnamehash).

The plugin type does not need to be specified because it can be derived from the context. Items like blog that do not have their own context will use their own file area inside a suitable context. In this case, the user context.

Entries with filename = '.' represent directories. Directory entries like this are created automatically when a file is added within them.

Note: 'files' plural is used even thought that goes against the [[Development:Database|coding guidelines]] because 'file' is a reserved word in some SQL dialects.

===Implementation of basic operations===

'''Each plugin may directly access only files in own context and areas!'''

Low level access API is defined in ''file_storage'' class which is obtained from <code>get_file_storage()</code>.

====Storing a file====

# Calculate the SHA1 hash of the file contents.
# Check if a file with this SHA1 hash already exists on disc in file directory or file trash. If not, store the file there.
# Add the record for this file to the files table using the low level address

====Reading a file====

# Fetch the record (which includes the SHA1 hash) for the file you want from the files table. You can fetch either all area files or quickly get one file with a specific contenthash.
# Retrieve the contents using the SHA1 hash from the file directory.

====Deleting a file====

# Delete the record from the files table.
# Verify if some other file is still needing the content, if not move the content file into file trash
# Later, admin/cron.php deletes content files from trash directory

== File serving ==

Deals with serving of files - browser requests file, Moodle sends it back. We have three main files. It is important to setup slasharguments on server properly (file.php/some/thing/xxx.jpg), any content that relies on relative links can not work without it (scorm, uploaded html pages, etc.).

=== legacy file.php ===

Serves legacy course files, the file name and parameter structure is critical for backwards compatibility of existing course content.

/file.php/courseid/dir/dir/filename.ext

Internally the files are stored in <code>array('contextid'=>$coursecontextid, 'component;=>'course', 'filearea'=>'legacy', 'itemid'=>0)</code>

The legacy course files are completely disabled in all new courses created in 2.0. The major problem here is to how to educate our users that they can not make huge piles of files in each course any more.

=== pluginfile.php ===
All plugins should use this script to serve all files.
* plugins decide about access control
* optional XSS protection - student submitted files must not be served with normal headers, we have to force download instead; ideally there should be second wwwroot for serving of untrusted files
* links to these files are constructed on the fly from the relative links stored in database, this means that plugin may link only own files

Absolute file links need to be rewritten if html editing allowed in plugin. The links are stored internally as relative links. Before editing or display the internal link representation is converted to absolute links using simple str_replace() @@thipluginlink/summary@@/image.jpg --> /pluginfile.php/assignmentcontextid/intro/image.jpg, it is converted back to internal links before saving.

Script parameters are virtual file names, in most cases the parameters match the low level file storage, but they do not have to:

/pluginfile.php/contextid/areaname/arbitrary/params/or/dirs/filename.ext

pluginfile.php detects the type of plugin from context table, fetches basic info (like $course or $cm if appropriate) and calls plugin function (or later method) which does the access control and finally sends the file to user. ''areaname'' separates files by type and divides the context into several subtrees - for example ''summary'' files (images used in module intros), post attachments, etc.

==== Assignment example ====

/pluginfile.php/assignmentcontextid/mod_assignment/intro/someimage.jpg
/pluginfile.php/assignmentcontextid/mod_assignment/submission/submissionid/attachmentname.ext
/pluginfile.php/assignmentcontextid/mod_assignment/allsubmissions/groupid/allsubmissionfiles.zip

The last line example of virtual file that should created on the fly, it is not implemented yet.

====scorm example====

/pluginfile.php/scormcontextid/mod_scorm/intro/someimage.jpg
/pluginfile.php/scormcontextid/mod_scorm/content/revisionnumber/dir/somescormfile.js

The revision counter is incremented when any file changes in order to prevent caching problems.

====quiz example====

pluginfile.php/quizcontextid/mod_quiz/intro/niceimage.jpg

====questions example====

This section was out of date. See [[Development:File_storage_conversion_Quiz_and_Questions]] for the latest thinking.

====blog example====
Blog entries or notes in general do not have context id (because they live in system context, SYSCONTEXTID below is the id of system context).
The note attachments are always served with XSS protection on, ideally we should use separate wwwroot for this. Access control can be hardcoded.

/pluginfile.php/SYSCONTEXTID/blog/attachment/blogentryid/attachmentname.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'component'=>'blog', 'filearea'=>'attachment', 'itemid'=>$blogentryid)</code>

/pluginfile.php/SYSCONTEXTID/blog/post/blogentryid/embeddedimage.ext

Internally stored in <code>array('contextid'=>SYSCONTEXTID, 'component'=>'blog', 'filearea'=>'post', 'itemid'=>$blogentryid)</code>

=== Temporary files ===
Temporary files are usually used during the lifetime of one script only.
uses:
* exports
* imports
* processing by executable files (latex, mimetex)

These files should never use utf-8 file names.

=== Legacy file storage and serving ===
Going to use good-old separate directories in $CFG->dataroot.

file serving and storage:
# user avatars - user/pix.php
# group avatars - user/pixgroup.php
# tex, algebra - filter/tex/* and filter/algebra/*
# rss cache (?full rss rewrite soon?) - backwards compatibility only rss/file.php

only storage:
#sessions

== File browsing API ==

This is what other parts of Moodle use to access files that they do not own.

=== Class: file_browser ===

=== Class: file_info and subclasses ===

== File related user interfaces ==

All files are obtained through from the file repositories.

=== Formslib fields ===
* file picker
* file manager
* file upload (obsolete, do not use)

=== Integration with the HTML editor ===

Each instance of the HTML editor can be told to store related files in a particular file area.

During editing, files are stored in a draft files area. Then when the form is submitted they are moved into the real file area.

Files are selected using the repository file picker.

=== Legacy file manager ===

Available only for legacy reasons. It is not supposed to be used.

All the contexts, file areas and files now form a single huge tree structure, although each user only has access to certain parts of that tree. The file manager (files/index.php) allow users to browse this tree, and manage files within it, according to the level of permissions they have.

Single pane file manager is hard to implement without drag & drop which is notoriously problematic in web based applications. I propose to implement a two pane commander-style file manager. Two pane manager allows you to easily copy/move files between two different contexts (ex: courses).

File manager must not interact directly with filesystem API, instead each module should return traversable tree of files and directories with both real and localised names (localised names are needed for dirs like backupdata).

== Backwards compatibility ==

=== Content backwards compatibility ===

This should be preserved as much as possible. This will involve rewriting links in content during the upgrade to 2.0.

Some new features (like resource sharing - if implemented) may not work with existing data that still uses files from course files area.

There might be a breakage of links due to special characters stripping in uploaded files which will not match the links in uploaded html files any more. This should not be very common I hope.

===Code backwards compatibility===

Other Moodle code (for example plugins) will have to be converted to the new APIs. See [[Development:Using_the_file_API]] for guidance.

It is not possible to provide backwards-compatibility here. For example, the old $CFG->dataroot/$courseid/ will no longer exist, and there is no way to emulate that, so we won't try.

== Upgrade and migration ==

When a site is upgraded to Moodle 2.0, all the files in moodledata will have to be migrated. This is going to be a pain, like DML/DDL was :-(

The upgrade process should be interruptible (like the Unicode upgrade was) so it can be stopped/restarted any time.

=== Migration of content ===

* resources - move files to new resource content file area; can be done automatically for pdf, image resources; definitely not accurate for uploaded web pages
* questions - image file moved to new area, image tag appended to questions
* moddata files - the easiest part, just move to new storage
* coursefiles - there might be many outdated files :-( :-(
* rss feeds links in readers - will be broken, the new security related code would break it anyway

=== Moving files to files table and file pool ===

The migration process must be interruptable because it might take a very long time. The files would be moved from old location, the restarting would be straightforward.

Proposed stages:
#migration of all course files except moddata - finish marked by some $CFG->files_migrated=true; - this step breaks the old file manager and html editor integration
#migration of blog attachments
#migration of question files
#migration of moddata files - each module is responsible to copy data from converted coursefiles or directly from moddata which is not converted automatically

Some people use symbolic links in coursefiles - we must make sure that those will be copied to new storage in both places, though they can not be linked any more - anybody wanting to have content synced will need to move the files to some repository and set up the sync again.

::Talked about a double task here, when migrating course files to module areas:
::# Parse html files to detect all the dependencies and move them together.
::# Fallback in pluginfile.php so, if something isn't found in module filearea, search for it in course filearea, copying it and finally, serving it.

:: Also we talked about the possibility of add a new setting to resource in order to define if it should work against old coursefiles or new autocontained file areas. Migrated resources will point to old coursefiles while new ones will enforce autocontained file areas.

:: it seems that only resource files will be really complex (because allow arbitrary HTML inclusion). The rest (labels, intros... doesn't) and should be easier to parse.

::[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 19:00, 29 June 2008 (CDT)

== Other issues ==

=== Unicode support in zip format ===

Zip format is an old standard for compressing files. It was created long before Unicode existed, and Unicode support was only recently added. There are several ways used for encoding of non-ASCII characters in path names, but unfortunately it is not very standardised. Most Windows packers use DOS encoding.

Client software:
* Windows built-in compression - bundled with Windows, non-standard DOS encoding only
* WinZip - shareware, Unicode option (since v11.2)
* TotalCommander - shareware, single byte(DOS) encoding only
* 7-Zip - free, Unicode or DOS encoding depending on characters used in file name (since v4.58beta)
* Info-ZIP - free, uses some weird character set conversions

PHP extraction:
* Info-ZIP binary execution - no Unicode support at all, mangles character sets in file names (depends on OS, see docs), files must be copied to temp directory before compression and after extraction
* PclZip PHP library - reads single byte encoded names only, problems with random problems and higher memory usage.
* Zip PHP extension - kind of works in latest PHP versions

Large file support:
PHP running under 32bit operating systems does not support files >2GB (do not expect fix before PHP 6). This might be a potential problem for larger backups.

Tar Alternative:
* tar with gzip compression - easy to implement in PHP + zlib extension (PclTar, Tar from PEAR or custom code)
* no problem with unicode in *nix, Windows again expects DOS encoding :-(
* seems suitable for backup/restore - yay!

Summary:
# added zip processing class that fully hides the underlying library
# using single byte encoding "garbage in/garbage out" approach for encoding of files in zip archives; add new 'zipencoding' string into lang packs (ex: cp852 DOS charset for Czech locale) and use it during extraction (we might support true unicode later when PHP Zip extension does that)

== Not implemented yet ==
* antivirus scanning - this needs a different api because the upload of files is now handled via repository plugins

== See also ==

* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* [[Development:Resource module file API migration]]
* MDL-14589 - File API Meta issue

{{CategoryDeveloper}}
[[Category:Files]]

[[ja:開発:ファイルAPI]]
[[ru:Development:File_API]]

Development:Matrix Question Type Specification

2021-07-14T13:24:31Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

==Introduction==

I need to develop a n:n matching type of question that is suited to a matrix.
The teacher should be able to define the matrix and the various grading options.

The follow serves as my very high level (mostly technical) specification.

===Some examples===

Here are three simple examples of the way this question type could be used. ( ) is mean to be a radio button. [ ] is a checkbox.

-----

Evaluate the following statements:

{|
! !! True !! False
|-
| Moodle is a learning management system || (*) || ( )
|-
| Mahara is an ePortfolio system || (*) || ( )
|-
| Moodle has no bugs || ( ) || (*)
|-
| This proposal is a good idea || (*) || ( )
|}

-----

Which colours are mixed on your computer's monitor to make each of the listed colours:

{|
! !! Red !! Green !! Blue
|-
| Red || [*] || [ ] || [ ]
|-
| Magenta || [*] || [ ] || [*]
|-
| Cyan || [ ] || [*] || [*]
|-
| Black || [ ] || [ ] || [ ]
|-
| White || [*] || [*] || [*]
|}

-----

Match the adult to their young:

{|
! !! Tadpole !! Joey !! Foal !! Puppy
|-
| Poney || ( ) || ( ) || (*) || ( )
|-
| Frog || (*) || ( ) || ( ) || ( )
|-
| Kangaroo || ( ) || (*) || ( ) || ( )
|}

But the most useful example is probably the Likert Scale:

How often do you do the following?

{|
! !! Never !! Very rarely !! Rarely !! Occasionally !! Frequently !! Very Frequently
|-
| Brush your teeth || [] || [ ] || [ ] || [*] || [ ] || []
|-
| Cook your own dinner || [*] || [ ] || [] || [] || [ ] || []
|-
| Make your bed || [ ] || [] || [] || [] || [ ] || [*]
|-
| Dye your hair || [ ] || [ ] || [ ] || [*] || [ ] || []
|-
| Pick your nose || [] || [] || [*] || [] || [ ] || []
|}

==Database Tables==

===Question Definition Tables===

====question_matrix====
Contains basic information about the matrix - what the grading method and
whether multiple checks per row are supported(eg checkboxes vs radio buttons)
The grading methods translate to:

* ALL - the student must select ALL correct answers and get 100%, else 0%.
* ANY - the student must select at least one of the correct answers, and get 100% else 0%.
* WEIGHTED - each cell has a weighting from -100% to 100%. The "correct" answers must add up to 100%, but the 0 and negative ones don't have any constraint on them.
* NONE - this could be used for example for Likert scales.

{| class="wikitable"
|-
!field
!notes
|-
|id
|sequence
|-
|questionid
|fk to mdl_question
|-
|multiple
|boolean
|-
|grading
|(ALL or ANY of WEIGHTED or NONE) enum or fk to another table containing these values.
|-
|roundzero
|If the total for the question is less than 0, set it to 0. (This can be triggered by highly negative weights)
|-
|renderer
|'matrix' hardcoded at the moment (see implementation notes)
|}

====question_matrix_cols====
Contains the definition of the matrix columns

{| class="wikitable"
|-
!field
!notes
|-
|id
|sequence
|-
|matrixid
|fk to question_matrix
|-
|shorttext
|short word to fit in
|-
|longtext
|title or hover or something
|}

====question_matrix_rows====
Contains the definition of the matrix rows

{| class="wikitable"
|-
!field
!notes
|-
|id
|sequence
|-
|matrixid
|fk to question_matrix
|-
|shorttext
|short word to fit in
|-
|longtext
|title or hover or something
|}

====question_matrix_weights====
Contains more information about how each cell should be graded.
EVERY cell should have an entry in this table. When the grading method is
'all' or 'any', the 'correct' answers will be stored here as a non-zero
percentage automatically and the non-correct answers will be zero.

{| class="wikitable"
|-
!field
!notes
|-
|id
|sequence
|-
|rowid
|fk to question_matrix_rows
|-
|colid
|fk to question_matrix_cols
|-
|weight
|percentage value
|}

===Student Answer Tables===

====question_matrix_answers====
This table contains a list of all the cells that the student has selected.

{| class="wikitable"
|-
!field
!notes
|-
|id
|sequence
|-
|rowid
|fk to question_matrix_rows
|-
|colid
|fk to question_matrix_cols
|}

==Implementation notes==

===Grading===
There should be classes to match the grading types (all or any or weighted) so
that new options could be written.

===Renderers===
It may make sense for some point for some different method to be used to render
this to the user, so we can start with a matrix class and maybe add more later
if necessary.

==Penny's TODO==

* Find out about roundzero
* Find out about constant namespacing in qtypes.

Development:Filter enable/disable by context

2021-07-14T13:24:30Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Moodle 2.0}}

We want to make configuration of filters more flexible, so, for example, you can do things like
* Disable the glossary auto-linking filter in a quiz.
* Enable the TeX filter only in the Maths course category.
* Have the glossary auto-linking filter link words from glossary A in forum A, and from glossary B in forum B.

Please discuss this proposal in [http://moodle.org/mod/forum/discuss.php?d=118580 this General Developer Forum thread].

==Overview==

Most filter settings will still be controlled at the system level. Administrators will still choose which filters enabled for the whole site, and, more importantly, which ones are not available at all. Also, most filter settings (for example which media types for the multimedia filter, and the paths for the TeX filter) will also still be set globally for the whole site by the administrator.

However, in addition to the overall on/off switch for each filter, we will store a separate active/inactive state for each filter in each context. (Don't worry, we don't actually store a row in the database for each context, mostly we use inheritance.) It will also be possible for a filter to have a settings screen for each context, and offer per-context settings, if it chooses to.

This proposal relies on some of the proposed navigation changes for Moodle 2.0, to give us a place to add a new 'Text filtering' setting link for each context.

==Detailed design==

===Changes to the filter admin screen===

On Administration ► Plugins ► Filters ► Manage filters, the existing Disable/Enable column will be changed to a column called '''Enabled?'''. For each filter there will be a dropdown with three choices:
* '''Disabled''' - not used at all on this site.
* '''Off, but available''' - available for use, but not turned on in the system context.
* '''On''' - available, and on in the system context, and elsewhere by default.

(A filter may need to be enabled, but not active globally, for example in the "TeX filter only in the maths course" use case.)

We will also add a Delete column to this table, to let administrators delete all the related configuration from the database if they uninstall a plugin.

====Add UI for $CFG->stringfilters====

At the moment, this setting is used in code, but there is no way to define it other than by writing directly to the config table in the database. We should add UI to it, probably at site level.

UI mockup on MDL-7336. Note, we will set both $CFG->filterallstrings and $CFG->stringfilters from the Apply to dropdowns. There will be now way to override those locally, but $CFG->stringfilters will be merged will the list of enabled filters in the context.

===New settings page in each context===

There will be a "Text filtering" settings page for each context (apart from block contexts), just like there are Assign roles and Override permissions pages.

The page will have a title something like "Text filtering in Course: Maths 101". It will contain a table with one row for each filter that the administrator has enabled. For each filter, there will be a drop-down with three choices: '''Default''', '''On''' and '''Off'''. For the default choice, it will display the value that would be inherited in brackets, for example "Default (on)". There will be a Save changes button at the bottom.

[[Image:Per-context_filter_settings_page.png]]

===Make possible per-filter settings page in each context===

Filters may create a file filterlocal.php in their plugin folder, and define a function has_local_config() in their filter.php file that returns true, if they want to offer different configuration options in different contexts.

This configuration is stored in in the filter_config table (see below).

Filter configuration does not inherit, and even if a filter has local configuration, it must be able to operate (perhaps by just doing nothing, or doing something default) if the local configuration variables are not set in the database.

(For example, the Glossary auto-linking filter might link to words from the course's primary glossary by default, but have a local settings page where a teacher can choose to link words from another glossary in this context.)

===New capability moodle/filter:manage===

Access to the global filter settings will still be controlled by moodle/site:config, becuase this is potentially risky.

Access to local override settings will be controlled by a new setting moodle/filter:manage. This capability has no associated risks, assuming that the admin has been sensible.

By default Administrators, Course creators and Teachers will have teh moodle/filter:manage capability.

===New database table filter_active===

This table replaces $CFG->textfilters.

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) AUTO-INCREMENT || Unique id
|-
| filter || VARCHAR(32) || e.g. 'filter/tex' or 'mod/glossary'
|-
| contextid || INT(10) || Foreign key references context.id
|-
| active || INT(4) || 1 = active, -1 = inactive. As a special case, if contextid == $systemcontext->id, then -9999 is used to mean that the administrator has disabled this filter.
|-
| sortorder || INT(10) || This is only used when contextid == $systemcontext->id. It stores the filter sort-order, numbering from 1. In other contexts, this column should contain 0.
|}

Whenever a context is deleted, we must delete the corresponding rows from this table.

We will not delete data from here when a filter is disabled globally, so that if the administrator disables then re-enables the filter, the setting in all the different contexts are not lost.

===New database table filter_config===

This stores filter configuration, as a set of name->value pairs, for each filter in each context. (By default, there will be 0 rows per filter per context.)

{| class="wikitable"
! Column !! Type !! Comment
|-
| id || INT(10) AUTO-INCREMENT || Unique id
|-
| filter || VARCHAR(32) || e.g. 'filter/tex' or 'mod/glossary'
|-
| contextid || INT(10) || Foreign key references context.id
|-
| name || VARCHAR(255) || The name of a setting variable
|-
| value || TEXT || The corresponding value
|}

Whenever a context is deleted, we must delete the corresponding rows from this table.

We will not delete data from here when a filter is disabled globally, so that if the administrator disables then re-enables the filter, the setting in all the different contexts are not lost.

===Retrieving the active filters for a page===

One of the Navigation 2.0 changes is that each page will be linked to a specific context. (That is, $PAGE->context will always to set to something sensible.)

Text will be filtered according to the page it appears on, not the context it belongs to. This is normally fine. For example, we want question text to be filtered according to the quiz that the question appears in.

With that in mind, suppose $contextids is the list of ids of this context and all its parents. Then the list of active filters is:

<code sql>
SELECT f.filter
FROM filter_active f
JOIN context ctx ON f.contextid = ctx.id
WHERE ctx.id IN ($contextids)
GROUP BY filter
HAVING MAX(f.active * ctx.depth) > -MIN(f.active * ctx.depth)
ORDER BY MAX(f.sortorder)
</code>

====Why does this work?====

To understand what that query is doing, you need to look at the results of

<code sql>
SELECT f.filter, f.contextid, ctx.depth, f.active, ctx.depth * f.active AS active_x_depth, f.sortorder
FROM filter_active f
JOIN context ctx ON f.contextid = ctx.id
WHERE ctx.id IN ($contextids)
ORDER BY f.filter, ctx.depth
</code>

That shows the data that is being aggregated by the GROUP BY and HAVING clauses. I will explain with reference to a specific example:

Suppose we are in a Quiz in the Maths 101 course in the Maths category in the system. $contextids = 1,3,10,22 (order reversed relative to the previous sentence - system context first). Then suppose that the above query returns

{| class="wikitable"
! filter !! contextid !! depth !! active !! active_x_depth !! f.sortorder
|-
| filter/mediaplugin || 1 || 1 || 1 || 1 || 1
|-
| filter/multilang || 1 || 1 || -1 || -1 || 1
|-
| filter/tex || 1 || 1 || -1 || -1 || 3
|-
| filter/tex || 3 || 2 || 1 || 2 || 0
|-
| filter/tidy || 1 || 1 || -9999 || -9999 || 4
|-
| filter/tidy || 22 || 4 || 1 || 4 || 0
|-
| mod/glossary || 1 || 1 || 1 || 1 || 2
|-
| mod/glossary || 3 || 2 || -1 || -2 || 0
|-
| mod/glossary || 10 || 3 || 1 || 3 || 0
|-
| mod/glossary || 22 || 4 || -1 || -4 || 0
|}

; filter/mediaplugin
: This is enabled, and active globally, and there are no overrides.
:* MAX(f.active * ctx.depth) = 1
:* MIN(f.active * ctx.depth) = 1
: 1 > -1, so this filter will be returned by the get active filters query.

; filter/multilang
: This is enabled, but not active globally, and there are no overrides.
:* MAX(f.active * ctx.depth) = -1
:* MIN(f.active * ctx.depth) = -1
: -1 ≯ 1, so this filter will '''not''' be returned by the get active filters query.

; filter/tex
: This is enabled, but not active globally. However, it has been activated in the Maths category.
:* MAX(f.active * ctx.depth) = 2
:* MIN(f.active * ctx.depth) = -1
: 2 > 1, so this filter will be returned by the get active filters query.

; filter/tidy
: This is '''not''' enabled, but there is an old override in the database
:* MAX(f.active * ctx.depth) = 4
:* MIN(f.active * ctx.depth) = -9999
: 4 ≯ 9999, so this filter will '''not''' be returned by the get active filters query.

; filter/glossary
: A slightly silly example with the maximum number of overrides possible. The most specific override is the one that says that the filter is not active in the quiz.
:* MAX(f.active * ctx.depth) = 3
:* MIN(f.active * ctx.depth) = -4
: 3 ≯ 4, so this filter will '''not''' be returned by the get active filters query.

; filter/myfilter
: What! there is no filter/myfilter in the data above. What is going on? This is the situation when the administrator has just installed the myfilter plugin, but has not yet been to the manage filters administration page to update the filter settings. What happens?
: Since there is nothing in the database, this filter is '''not''' returned by the get active filters query. That is, a newly installed filter is not active until the administrator explicitly activates it.

'''Sort order''': Note that sortorder is zero except when contextid = 1. So MAX(f.sortorder) is just a clever trick to pull out the sortorder from the system context, ignoring all the zeros. There are other tricks that could be used instead, but this one is probably quite efficient.

===Getting filter configuration===

Actually, we will get the filter configuration in the same database query that we get the list of active filters. So the actual query used will be:

<code sql>
SELECT active.filter, fc.name, fc.value
FROM (SELECT f.filter
FROM filter_active f
JOIN context ctx ON f.contextid = ctx.id
WHERE ctx.id IN ($contextids)
GROUP BY filter
HAVING MAX(f.active * ctx.depth) > -MIN(f.active * ctx.depth)
ORDER BY MAX(f.sortorder)) active
LEFT JOIN filter_config fc ON fc.filter = active.filter AND fc.contextid = $contextid
</code>

This will be done in a function get_active_filters that looks like:

<code php>
/**
* Get the list of active filters, in the order that they should be used
* for a particular context.
*
* @param object $context a context
*
* @return array an array where the keys are the filter names, for example
* 'filter/tex' or 'mod/glossary' and the values are any local
* configuration for that filter, as an array of name => value pairs
* from the filter_config table. In a lot of cases, this will be an
* empty array. So, an example return value for this function might be
* array('filter/tex' => array(), 'mod/glossary' => array('glossaryid', 123))
*/
function get_active_filters($context) {
// ...
}
</code>

===Changes to text caching===

The md5key used in the cache_text table will be changed to user the contextid, rather than the courseid, in $hashstr. See format_text in weblib.php.

===Backup and restore===

This will be similar in some ways to the roles backup and restore code, in that it needs to do work for every context in the backup file.

On backup (in lib/backuplib.php), everywhere it does write_role_overrides_xml and write_role_assignments_xml we need to add a call to a new function write_filter_actives_xml. (I think we need a write_context_data_xml function to avoid duplicating the calls to those three functions in lots of places.) That function can write XML like
<code xml>
<FILTERACTIVES>
<FILTERACTIVE>
<FILTER>filter/tex</FILTER>
<ACTIVE>+1</ACTIVE>
<FILTERACTIVE>
<FILTERACTIVE>
<FILTER>mod/glossary</FILTER>
<ACTIVE>-1</ACTIVE>
<FILTERACTIVE>
</FILTERACTIVES>
<FILTERCONFIGS>
<FILTERCONFIG>
<FILTER>filter/tex</FILTER>
<NAME>glossaryid</NAME>
<VALUE>123</VALUE>
<FILTERCONFIG>
<FILTERCONFIGS>
</code>

In the function restore_execute in backup/restorelib.php, probably just after the bit that calls restore_roles_settings, add a call to restore_filter_actives. This needs to read each FILTERACTIVE record from the backup file, check whether the corresponding filters in installed on this Moodle site, and if it is, write the record to the filter_active table using the recoded contextid.

==Possible problems==

===Is filtering by page context really the right thing?===

Filtering according to page context might cause strange results on pages that aggregate content from different contexts.

For example, we normally think that the user's profile page is in the user context. That would mean that the Recent activity report there will be filtered according to the filter settings for the user context. (These will almost certainly inherit unmodified from the System context.) That would be strange if the TeX filter was only enabled in the Maths course. However, it may work better (both here and elsewhere) if we set $PAGE->context to the course context for profile pages like this.

On the other hand, if the parent looking at their child's recent activity does not have access to the course, it is good that they do not see the effects of the glossary auto-linking filter, which would like them to glossary entries they do not have permission to see.

The real problem page, would, of course, be the My Moodle page. That could aggregate content from any number of different contexts.

Or, we may find that we have to add a $contextid parameter to the format_text function, and find some way to avoid the performance problems that causes. (It would be really bad to query the database with a query like the one above for each call to format_text. Or even for each context that contributes content to the My Moodle page.)

At the moment, the plan is to ignore this problem. This proposal adds a significant new functionality, and this one problem does not stop it from being very useful in most cases.

==See also==

* [[Development:Navigation_2.0]]
* MDL-7336
* [http://moodle.org/mod/forum/discuss.php?d=118580 this General Developer Forum thread].
* [[Development:Filters]] - the documentation that will need to be updated.

{{CategoryDeveloper}}
[[Category:Filter]]

Using TeX Notation

2021-07-14T13:24:23Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Filters}}
{{Work in progress}}
TeX ('''/'tɛx/tekh''', often pronounced TeK in English) is a very widespread and popular way of representing Mathematics notation using only characters that you can type on a keyboard (see [https://en.wikipedia.org/wiki/TeX Wikipedia]). This makes it a useful format to use in Moodle, since it can be entered anywhere you can type text, from forum posts to quiz questions.

TeX expressions can be entered in multiple ways:
* typing them directly into texts.
* using the Java-based Dragmath editor in Moodle's TinyMCE editor.
* using the HTML-based equation editor in Moodle's Atto editor (since Moodle 2.7).

Afterwards, TeX expressions are rendered into Mathematics notation:
* using the TeX filter in Moodle, which uses a TeX binary installed on the server to convert expressions into .gif images (or if that is not available, it falls back to a simple built-in mimetex binary).
* using the [[MathJax_filter]] which identifies TeX expressions and uses the Mathjax JS library to render them in browsers at display time (since Moodle 2.7).
* using other third-party solutions.

As you can imagine, the whole field is not as simple as we would like, especially because there are many flavours of TeX and slight variations between tools.

This page focusses only on using TeX in core Moodle. See the links at the bottom of this page for more information on setting up TeX editors and filters, including other tools from the Moodle community that may be suitable for advanced users.

'''WARNING:''' This Wiki environment uses a DIFFERENT TeX renderer to Moodle, especially when it comes to control sequences. For this reason images are sometimes used to represent what it should look like in Moodle. YMMV.

==Language Conventions==

To identify a TeX sequence in your text, surround it with $$ markers. To invoke a particular command or control sequence, use the backslash, \. A typical control sequence looks like:

$$ x\ =\ \frac{\sqrt{144}}{2}\ \times\ (y\ +\ 12) $$
{| class="wikitable"
|-
| [[Image: cfmimetex10.gif|frame|center]]
|-
|Fraction and square root.
|}

Additional spaces can be placed into the equation using the \ without a trailing character.

==Equation displayed on its own line==
When an equation is surrounded by a pair of $$ markers, it is displayed centered on its own line. The $$’s are primitive TeX markers. With LaTeX, it is often recommended to use the pair \[ and \] to enclose equations, rather than the $$ markers, because the newer syntax checks for mistyped equations and better adjusts vertical spacing. If the TeX Notation filter is activated, which set a LaTeX renderer, the same equation as above is obtained with the following control sequence:

<span style="background-color:yellow;">\[</span> x\ =\ \frac{\sqrt{144}}{2}\ \times\ (y\ +\ 12) <span style="background-color:yellow;">\]</span>

However, if the equation is mistyped, it will be displayed enclosed in a box to signal the mistake and if the equation appears in a new paragraph, the vertical space above the equation will adjust correctly.

Using \[ … \] instead of $$ … $$ may have other advantages. For example, with the Wiris equation editor installed, the Atto editor undesirably transforms the TeX code of equations enclosed with $$ into XML code, whereas it does not do so when the equations are enclosed with \[ and \].

==Equation displayed within text==
With the TeX notation filter activated, an equation is displayed within the text when it is surrounded by the pair $ and $. For example, the following:

The point <span style="background-color:yellow;">$</span> \left( {{x}_{0}}+\frac{1}{p\left( {{x}_{0}} \right)}\ ,\ \frac{q\left( {{x}_{0}} \right)}{p\left( {{x}_{0}} \right)} \right) <span style="background-color:yellow;">$</span> is located...

will display as follows:

[[File:TeXEquationWithinText.png|320px]]

Note that the single $ marks may not work for this purpose.

==Reserved Characters and Keywords==

Most characters and numbers on the keyboard can be used at their default value. As with any computing language, though, there are a set of reserved characters and keywords that are used by the program for its own purposes. TeX Notation is no different, but it does have a very small set of Reserved Characters. This will not be a complete list of reserved characters, but some of these are:

@ # $ % ^ & * ( ) .

To use these characters in an equation just place the \ in front of them like \$ or \%. If you want to use the backslash, just use \backslash. The only exception here seems to be the &, ampersand.

==Superscripts, Subscripts and Roots==

Superscripts are recorded using the caret, ^, symbol. An example for a Maths class might be:

$$ 4^2 \ \times \ 4^3 \ = 4^5 $$
This is a shorthand way of saying:
(4 x 4) x (4 x 4 x 4) = (4 x 4 x 4 x 4 x 4)
or
16 x 64 = 1024.

<math>4^2 \ \times \ 4^3 \ = 4^5</math>

Subscripts are similar, but use the underscore character.

$$ 3x_2 \ \times \ 2x_3 $$

<math>3x_2 \ \times \ 2x_3</math>

This is OK if you want superscripts or subscripts, but square roots are a little different. This uses a control sequence.

$$ \sqrt{64} \ = \ 8 $$

<math>\sqrt{64} \ = \ 8</math>

You can also take this a little further, but adding in a control character. You may ask a question like:

$$ If \ \sqrt[n]{1024} \ = \ 4, \ what \ is \ the \ value \ of \ n? $$

<math>If \ \sqrt[n]{1024} \ = \ 4, \ what \ is \ the \ value \ of \ n?</math>

Using these different commands allows you to develop equations like:

$$ The \sqrt{64} \ \times \ 2 \ \times \ 4^3 \ = \ 1024 $$

<math>The \sqrt{64} \ \times \ 2 \ \times \ 4^3 \ = \ 1024</math>

Superscripts, Subscripts and roots can also be noted in [[Using TeX Notation 4 | Matrices]].

==Fractions==

Fractions in TeX are actually simple, as long as you remember the rules.

$$ \frac{numerator}{denominator} $$ which produces <math>\frac{numerator}{denominator}</math> .

This can be given as:

<math>\frac{5}{10} \ is \ equal \ to \ \frac{1}{2}</math>.

This is entered as:

$$ \frac{5}{10} \ is \ equal \ to \ \frac{1}{2}.$$

With fractions (as with other commands) the curly brackets can be nested so that for example you can implement negative exponents in fractions. As you can see,

$$\frac {5^{-2}}{3}$$ will produce <math>\frac {5^{-2}}{3}</math>

$$\left(\frac{3}{4}\right)^{-3}$$ will produce <math>\left(\frac{3}{4}\right)^{-3}</math> and

$$\frac{3}{4^{-3}}$$ will produce <math> \frac{3}{4^{-3}} </math>

You likely do not want to use $$\frac{3}{4}^{-3}$$ as it produces <math>\frac{3}{4}^{-3}</math>

You can also use fractions and negative exponents in [[Using TeX Notation 4 | Matrices]].

==Brackets==

As students advance through Maths, they come into contact with brackets. Algebraic notation depends heavily on brackets. The usual keyboard values of ( and ) are useful, for example:

<math>d = 2 \ \times \ (4 \ - \ j)</math>

This is written as:

$$ d = 2 \ \times \ (4 \ - \ j) $$

Usually, these brackets are enough for most formulae but they will not be in some circumstances. Consider this:

<math>4x^3 \ + \ (x \ + \ \frac{42}{1 + x^4})</math>

Is OK, but try it this way:

<math>4x^3 \ + \ \left(x \ + \ \frac{42}{1 + x^4}\right)</math>

This can be achieved by:

$$ 4x^3 \ + \ \left(x \ + \ \frac{42}{1 + x^4}\right) $$

A simple change using the \left( and \right) symbols instead. Note the actual bracket is both named and presented. Brackets are almost essential in [[Using TeX Notation 4 | Matrices]].

==Ellipsis==

The Ellipsis is a simple code:

<math>x_1, \ x_2, \ \ldots, \ x_n</math>

Written like:

$$ x_1, \ x_2, \ \ldots, \ x_n $$

A more practical application could be:

Question:
"Add together all the numbers from 1 <math>\ldots</math> 38.
What is an elegant and simple solution to this problem?
Can you create an algebraic function to explain this solution?
Will your solution work for all numbers?"

Answer:
The question uses an even number to demonstrate a mathematical process and generate an algebraic formula.

{| class = "nicetable"
|-
| Part 1:
| Part 2.
| Part 3.
|-
|
<math>1. \ 1 \ + \ 38 \ = \ 39</math>

<math>2. \ 2 \ + \ 37 \ = \ 39</math>

<math>3. \ 3 \ + \ 36 \ = \ 39</math>

<math>\ldots</math>

<math>19. 19 \ + \ 20 \ = \ 39 </math>

<math>\therefore x \ = \ 39 \ \times \ 19 </math>

<math>\therefore x \ = \ 741 </math>

|An algebraic function might read something like:
<math>t = (1 + n) \times n/2 </math>

Where t = total and n = the last number.

|The solution is that, using the largest and the smallest numbers, the numbers are added and then multiplied by the number of different combinations to produce the same result adding the first and last numbers.
The answer must depend on the number, <math>\frac{n}{2}</math> being a whole number. Therefore, the solution will not work for an odd range of numbers, only an even range.

|}

==Symbols==

These are not all the symbols that may be available in TeX Notation for Moodle, just the ones that I have found to work in Moodle.

{| class="wikitable"
|-
| \amalg
| <math>\amalg</math>
| \cup
| <math>\cup</math>
| \oplus
| <math>\oplus</math>
| \times
| <math>\times</math>
|-
|\ast
|<math>\ast</math>
|\dagger
|<math>\dagger</math>
| \oslash
| <math>\oslash</math>
| \triangleleft
| <math>\triangleleft</math>
|-
| \bigcirc
| <math>\bigcirc</math>
| \ddagger
| <math>\ddagger</math>
| \otimes
| <math>\otimes</math>
| \triangleright
| <math>\triangleright</math>
|-
| \bigtriangledown
| <math>\bigtriangledown</math>
| \diamond
| <math>\diamond</math>
| \pm
| <math>\pm</math>
| \odot
| <math>\odot</math>
|-
| \bigtriangleup
| <math>\bigtriangleup</math>
| \div
| <math>\div</math>
| \ominus
| <math>\ominus</math>
| \wr
| <math>\wr</math>
|-
| \circ
| <math>\circ</math>
| \wedge
| <math>\wedge</math>
| \vee
| <math>\vee</math>
| \sqcup
| <math>\sqcup</math>
|-
| \leq
| <math>\leq</math>
| \geq
| <math>\geq</math>
| \equiv
| <math>\equiv</math>
| \prec
| <math>\prec</math>
|-
| \succ
| <math>\succ</math>
| \sim
| <math>\sim</math>
| \perp
| <math>\perp</math>
| \preceq
| <math>\preceq</math>
|-
| \succeq
| <math>\succeq</math>
| \simeq
| <math>\simeq</math>
| \mid
| <math>\mid</math>
| \ll
| <math>\ll</math>
|-
| \gg
| <math>\gg</math>
| \asymp
| <math>\asymp</math>
| \parallel
| <math>\parallel</math>
| \subset
| <math>\subset</math>
|-
| \supset
| <math>\supset</math>
| \subseteq
| <math>\subseteq</math>
| \supseteq
| <math>\supseteq</math>
| \approx
| <math>\approx</math>
|-
| \neq
| <math>\neq</math>
| \ni
| <math>\ni</math>
| \notin
| <math>\notin</math>
| \in
| <math>\ni</math>
|-
| \vdash
| <math>\vdash</math>
| \dashv
| <math>\dashv</math>
| \bullet
| <math>\bullet</math>
| \cdot
| <math>\cdot</math>
|}

==Arrows==

{| class="wikitable"
|-
| \leftarrow
| <math> \leftarrow</math>
| \longleftarrow
| <math> \longleftarrow</math>
| \Leftarrow
| <math> \Leftarrow</math>
| \Longleftarrow
| <math> \Longleftarrow</math>
|-
| \rightarrow
| <math> \rightarrow</math>
| \longrightarrow
| <math> \longrightarrow</math>
| \Rightarrow
| <math> \Rightarrow</math>
| \Longrightarrow
| <math> \Longrightarrow</math>
|-
| \uparrow
| <math> \uparrow</math>
| \Uparrow
| <math> \Uparrow</math>
| \downarrow
| <math> \downarrow</math>
| \Downarrow
| <math> \Downarrow</math>
|-
| \leftrightarrow
| <math> \leftrightarrow</math>
| \longleftrightarrow
| <math> \longleftrightarrow</math>
| \updownarrow
| <math> \updownarrow</math>
| \Updownarrow
| <math> \Updownarrow</math>
|-
| \Leftrightarrow
| <math> \Leftrightarrow</math>
| \Longleftrightarrow
| <math> \Longleftrightarrow</math>
| \leftrightharpoons
| <math> \rightleftharpoons</math>
| \Im
| <math> \Im</math>
|-
| \nearrow
| <math> \nearrow</math>
| \nwarrow
| <math> \nwarrow</math>
| \swarrow
| <math> \swarrow</math>
| \searrow
| <math> \searrow</math>

|}

==Delimiters and Maths Constructs==

NOTE: Most delimiters and constructs need additional parameters for them to appear appropriately.

{| class="wikitable"
|-
| \{x
| <math> \{x </math>
| x | \}
| <math>x | \} </math>
| \rangle
| <math> \rangle </math>
| \langle
| <math> \langle </math>
|-
| \angle
| <math> \angle </math>
| \=
| <math> \| </math>
| \sqrt{ab}
| <math> \sqrt{ab}</math>
| \sqrt[n]{ab}
| <math> \sqrt[n]{ab}</math>
|-
| \frac{ab}{cd}
| <math> \frac{ab}{cd}</math>
| \backslash
| <math> \backslash</math>
| \widehat{ab}
| <math> \widehat{ab}</math>
| \$
| <math> \$ </math>
|-
| \overline{ab}
| <math> \overline{ab}</math>
| \underline{ab}
| <math> \underline{ab}</math>
| \therefore
| <math> \therefore</math>
| \ddots
| <math> \ddots</math>
|-
| \%
| <math> \%</math>
| \#
| <math> \# </math>
| \vdots
| <math> \vdots</math>
| \emptyset
| <math> \emptyset</math>
|}
WARNINGS: The & character in LaTeX usually requires a backslash, \. In TeX Notation for Moodle, apparently, it does not. Other packages, AsciiMath, may use it differently again so be careful using it. The copyright character may use the MimeTeX charset, and produces a copyright notice for John Forkosh Associates who provided a lot of the essential packages for the TeX Notation for Moodle, so I understand. I have been, almost reliably, informed that a particular instruction will produce a different notice though .:)

There are also a number of characters that can be used in TeX Notation for Moodle but do not render in this page:

{| class="wikitable"
|-
| [[Image: cfmimetex08.png|frame|left]]
| Larger \left(x and \right) brackets
|-
|[[Image: cfmimetex06.gif|frame|left]]
| \widetilde{ab}
|-
|[[Image: cfmimetex09.gif|frame|left]]
| \textdegree or (50)^\circ
|}

==Greek Letters==

{| class="wikitable"
|-
| <math>\alpha</math>
| \alpha
| <math>\beta</math>
| \beta
| <math>\gamma</math>
| \gamma
|-
| <math>\delta</math>
| \delta
| <math>\epsilon</math>
| \epsilon
| <math>\zeta</math>
| \zeta
|-
| <math>\eta</math>
| \eta
| <math>\theta</math>
| \theta
| <math>\iota</math>
| \iota
|-
| <math>\kappa</math>
| \kappa
| <math>\lambda</math>
| \lambda
| <math>\mu</math>
| \mu
|-
| <math>\xi</math>
| \xi
| <math>\pi</math>
| \pi
| <math>\rho</math>
| \rho
|-
| <math>\sigma</math>
| \sigma
| <math>\tau</math>
| \tau
| <math>\upsilon</math>
| \upsilon
|-
| <math>\phi</math>
| \phi
| <math>\chi</math>
| \chi
| <math>\psi</math>
| \psi
|-
| <math>\omega</math>
| \omega
| <math>\Omega</math>
| \Omega
| <math>\Theta</math>
| \Theta
|-
| <math>\Delta</math>
| \Delta
| <math>\Pi</math>
| \Pi
| <math>\Phi</math>
| \Phi
|-
| <math>\Gamma </math>
| \Gamma
| <math>\Lambda </math>
| \Lambda
| <math>\Sigma </math>
| \Sigma
|-
| <math>\Psi </math>
| \Psi
| <math>\Xi </math>
| \Xi
| <math>\Upsilon</math>
| \Upsilon
|-
| <math>\vartheta </math>
| \vartheta
| <math>\varrho </math>
| \varrho
| <math>\varphi </math>
| \varphi
|-
| <math>\varsigma </math>
| \varsigma
|}

'''Notable Exceptions'''

Greek letter omicron (traditionally, mathemeticians don't make much use of omicron due to possible confusion with zero). Simply put, lowercase omicron is an "o" redered as <i>o</i>. But note \omicron may now work with recent TeX implementations including MathJax.

At the time of writing, these Greek capital letters cannot be rendered by TeX Notation in Moodle:

Alpha, Beta, Zeta, Eta, Tau, Chi, Mu, Iota, Kappa and Epsilon.

TeX methematics adopts the convention that lowercase Greek symbols are displayed as italics whereas uppercase Greek symbols are displayed as upright characters. Therefore, the missing Greek capital letters can simply be represented by the \mathrm{ } equivalent

<math>\mathrm{A, B, Z, H, T, X, M, I, K, E}</math>

==Boolean algebra==

There are a number of different conventions for representing Boolean (logic) algebra. Common conventions used in computer science and electronics are detailed below:

Negation, NOT, ¬, !, ~, <sup>−</sup>
\lnot, !, \sim, \overline{ }
Conjunction, AND, ∧, <math>\cdot</math>
\land, \wedge, \cdot
Dysjunction, OR, ∨, +,
\lor, \vee, +
Exclusive dysjunction, XOR ⊻, ⊕
\veebar, \oplus
Equivalence, If and only if, Iff, ≡, ↔, ⇔
\equiv, \leftrightarrow \iff

Example: two representations of De Morgan's laws:

<math>A \cdot B = \overline{\overline{A} + \overline{B}}</math>
$$ A \cdot B = \overline{\overline{A} + \overline{B}} SS

<math>(A \land B) \equiv \lnot(\lnot{A} \lor \lnot{B})</math>
$$ (A \land B) \equiv \lnot(\lnot{A} \lor \lnot{B}) $$

==Fonts==

To use a particular font you need to access the font using the same syntax as demonstrated above.

A math calligraphic font:

<math>\mathcal{ABCDEFGHIJKLMNOPQRSTUVXYZ}</math>

or

$$ \mathcal{ABCDEFGHIJKLMNOPQRSTUVXYZ}$$

Blackboard bold, a Castellar type font:

<math>\mathbb{ABCDEFGHIJKLMNOPQRSTUVXYZ}</math>

or

$$ \mathbb{ABCDEFGHIJKLMNOPQRSTUVXYZ}$$

Often used in number theory. For example: <math>\mathbb{N}</math> = set of natural numbers including 0 {0, 1, 2, 3, ...}, <math>\mathbb{Z}</math> = set of integers {-..., -3, -2, -1, 0, 1, 2, 3, ... }, <math>\mathbb{Q}</math> = set of rational numbers, including integers, <math>\mathbb{R}</math> = set of real numbers, which includes the natural numbers, rational numbers and irrational numbers.

Fraktur, an Old English type font:

<math>\mathfrak{ABCDEFGHIJKLMNOPQRSTUVXYZ}</math>

or

$$ \mathfrak{ABCDEFGHIJKLMNOPQRSTUVXYZ}$$

This is different in Tex Notation in Moodle than it is for other, full, TeX packages.

An italic font:

<math>\mathit{ABCDEFGHIJKLMNOPQRSTUVXYZ}</math>

or

$$ \mathit{ABCDEFGHIJKLMNOPQRSTUVXYZ} $$

A normal, upright non-italic, Roman font:

<math>\mathrm{ABCDEFGHIJKLMNOPQRSTUVXYZ}</math>

or

$$ \mathrm{ABCDEFGHIJKLMNOPQRSTUVXYZ} $$
A bold-face font:

<math>\mathbf{ABCDEFGHIJKLMNOPQRSTUVXYZ}</math>

or

$$ \mathbf{ABCDEFGHIJKLMNOPQRSTUVXYZ} $$

==Size of displays==

The default size is rendered slightly larger than normal font size. TeX Notation in Moodle uses eight different sizes ranging from "tiny" to "huge". However,these values seem to mean different things and are, I suspect, dependent upon the User's screen resolution. The sizes can be noted in four different ways:

{| class="wikitable"
|-
| \fontsize{0} to \fontsize{7}
| $$\fontsize{2} x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12)$$
| [[Image:cfmimetex10.gif|left]]
|-
| \fs{0} to \fs{7}
| $$\fs{4} x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12)$$
| [[Image:cfmimetex10.gif|left]]
|-
| \fs0 to \fs7
| $$\fs6 x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12)$$
| [[Image:cfmimetex11c.gif|left]]
|-
| As well, you can use \tiny \small
\normalsize \large \Large
\LARGE \huge \Huge
| $$\normalsize x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12)$$
| [[Image:cfmimetex11d.gif|left]]
|}

It appears that TeX Notation in Moodle now allows \fs6, \fs7, \huge and \Huge to be properly rendered.

==Colour==

Unlike many scripting languages, we only need to name the colour we want to use. You may have to experiment a little with colours, but it will make for a brighter page. Once named, the entire statement will appear in the colour, and if you mix colours, the last named colour will dominate. Some examples:

{| class="wikitable"
|-
| $$ \red x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12) $$
| [[Image: cfmimetex30a.gif|right]]
|-
| $$ \blue x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12) $$
| [[Image: cfmimetex30b.gif|right]]
|-
| $$ \green x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12) $$
| [[Image: cfmimetex30c.gif|right]]
|-
| $$ \red x \ = \ \frac{\sqrt{144}}{2}$$ $$ \times $$
$$\green (y \ + \ 12) $$ $$ \ = $$ $$ \ \blue 6^3 $$
| [[Image: cfmimetex30d.gif|right]]
|}

Moodle 2.2 note: You may find this doesn't work for you. You can try to add "\usepackage{color}" to your tex notation setting "LaTeX preamble" (under Site adminstration/Plugins/Filters/TeX notation)and then use this new syntax: $$ \color{red} x \ = \ \frac{\sqrt{144}}{2} \ \times \ (y \ + \ 12) $$

You may note this last one, it is considerably more complex than the previous for colours. TeX Notation in Windows does not allow multicoloured equations, if you name a number of colours in the equation, only the last named will be used.

==Geometric Shapes==

There are two ways to produce geometric shapes, one is with circles and the other is with lines. Each take a bit of practice to get right, but they can provide some simple geometry. It may be easier to produce the shapes in Illustrator or Paint Shop Pro or any one of a number of other drawing packages and use them to illustrate your lessons, but sometimes, some simple diagrams in Moodle will do a better job.

==Circles==

Circles are easy to make.

{| class="wikitable"
|-
| [[Image:cfmimetex20.gif|left]]
| Circles are easily created, and only needs a number to determine how large the circle is.
To create the circle use $$ \circle(150) $$. This makes a circle of 150 pixels in diameter.

|}

==Creating Arcs==

Arcs are also easy to produce, but require some additional parameters. The same code structure used in circles create the basic shape, but the inclusion of a start and end point creates only the arc. However, notice where the 0 point is, not at the true North, but rather the East and run in an anti-clockwise direction.

{| class="wikitable"
|-
| [[Image:cfmimetex21a.gif|left]]
| $$ \circle(120;90,180)$$
| [[Image:cfmimetex21b.gif|left]]
| $$ \circle(120;0,90)$$
|-
| [[Image:cfmimetex21c.gif|left]]
| $$ \circle(120;180,270)$$
| [[Image:cfmimetex21d.gif|left]]
| $$ \circle(120;270,360)$$
|}

This structure breaks down into the \circle command followed by the diameter, not the radius, of the circle, followed by a semi-colon, then the demarcation of the arc, the nomination of the start and end points in degrees from the 0, East, start point. Note that the canvas is the size of the diameter nominated by the circle's parameters.

==The \picture Command==

Using circles and arcs as shown above is somewhat limiting. The \picture command allows you to use a frame in which to build a picture of many layers. Each part of the picture though needs to be in its own space, and while this frame allows you to be creative, to a degree, there are some very hard and fast rules about using it.

All elements of a picture need to be located within the picture frame. Unexpected results occur when parts of an arc, for example, runs over the border of the frame. (This is particularly true of lines, which we will get to next, and the consequences of that overstepping of the border can cause serious problems.)

The \picture command is structured like:
\picture(100){(50,50){\circle(200)}}
\command(size of frame){(x co-ordinate, y co-ordinate){\shape to draw(size or x co-ordinate, y co-ordinate)})

'''NOTE:''' The brace is used to enclose each set of required starting point coordinates. Inside each set of braces, another set of braces is used to isolate each set of coordinates from the other, and those coordinates use their proper brackets and backslash. Count the opening and closing brackets, be careful of the position,

{| class="wikitable"
|-
| [[Image:cfmimetex24a.gif|left]]
| $$ \picture(100){(50,50){\circle(200)}}&&

The picture frame brings elements together that you may not otherwise see.

Because of the frame size of 100px and the centre point of the circle in the mid-point of the frame, the 200px circle will be squashed. Unexpected results occur when sizes are not correct.
| [[Image:cfmimetex24b.gif|left]]
|
Using the picture frame, you can layer circles
and lines over each other, or they can intersect.

$$ \picture(100){(50,50){\circle(99)} (50,50){\circle(80)}} $$
|-
| [[Image:cfmimetex24c.gif|left]]
| You may want to see an image of a circle with a dot in the middle.
You may have to try to place the centre dot correctly , but the
ordering of the elements in the image may have an impact.

$$ \picture(100){(48,46){\bullet}(50,50){\circle(99)}} $$
| [[Image:cfmimetex24d.gif|left]]
| Using the same ideas as above, you can make semi-circles.

$$\picture(150){(50,50){\circle(100;0,180)}(100,50){\circle(100;180,360)}}$$
|}

==Lines==

----

'''Warning:''' Drawing lines in TeX Notation in Moodle is an issue, go to the [[Using_TeX_Notation#Reserved_Characters_and_Keywords| Using Text Notation]] for more information. If the line is not noted properly then the parser will try to correctly draw the line but will not successfully complete it. This means that every image that needs be drawn will be drawn until it hits the error. When the error is being converted, it fails, so no subsequent image is drawn. Be careful and make sure your line works BEFORE you move to the next problem or next image.

----
{| class="wikitable"
|-
| [[Image: cfmimetex26.gif|frame|left| a couple of lines]]
| $$\red \picture(200){(20,0){ \line(180,0)}{(20,180){\line(180,0}$$

The structure of the picture box is that the \picture(200) provides a square image template.

The (20,0) provides the starting coordinates for any line that comes after. In this case the start point is at 20pixels in the x axis and 0 pixels in the y axis. The starting point for all coordinates, 0,0, is the bottom left corner and they run in a clockwise manner. '''Do not confuse this with arcs.'''

The \line(180,0) determines the length and inclination of the line. In this case, the inclination is 0 and the length is 180px.

These are enclosed in braces, all inside one set of braces owned by the \picture() control sequence.

The next set of commands are the same, that is, the (20,200) are the coordinates of the next line. The x co-ordinate is the 20, that is the distance to the right from the 0 point. The y co-ordinates is the distance from the bottom of the image. Whereas the first line started and ran on the bottom of the picture frame, the y co-ordinate starts at the 200 pixel mark from the bottom of the image. The line, at 180 pixels long and has no y slope. This creates a spread pair of parallel lines.
| [[Image: cfmimtex27.gif|thumb|right|150px|\picture explained]]
|}

While this explains the structure of a line, there is a couple of elements that you need to go through to do more with them.

==Squares and Rectangles==
Drawing squares and rectangles is similar, but only slightly different.

There should be a square box tool, and there is, but unless it has something inside it, it does not display. It is actually easier to make a square using the \line command.

{| class="wikitable"
|-
| [[Image: line03.gif|left]]
|This box is constructed using:
$$ \picture(250){(10,10){\line(0,230)}(10,10){\line(230,0)}(240,10){\line(0,230)}(10,240){\line(230,0)}}$$
It is a 250 pixel square box with a 230 pixel square inside it.
| [[Image: line04.gif|left]]
|This box is different in that is has the equal length indicators that are used in a square.
$$ \picture(250){(10,10){\line(0,230)}
(5,120){\line(10,0)}
(10,10){\line(230,0)}
(120,5){\line(0,10)}
(240,10){\line(0,230)}
(235,120){\line(10,0)}
(10,240){\line(230,0)}
(120,235){\line(0,10)}}$$
|-
| [[Image: line05.gif|left]]
| The rectangle then becomes the same thing, but with one side shorter. For a portrait canvas it would be:
$$ \picture(250){(10,10){\line(0,230)}(10,10){\line(150,0)}(160,10){\line(0,230)}(10,240){\line(150,0)}}$$
| [[Image: line06.gif|left]]
|The rectangle can also produce a landscape shape:
$$ \picture(250){(10,10){\line(0,160)}(10,10){\line(230,0)}(240,10){\line(0,160)}(10,170){\line(230,0)}}$$
|}

==Controlling Angles==

Controlling angles is a little different. They involve a different perception, but not one that is unfamiliar. Consider this:

We have a point from which we want to draw a line that is on an angle. The notation used at this point can be positive, positive or positive, negative or negative, positive or negative, negative. Think of it like a number plane or a graph, using directed numbers. The 0,0 point is in the centre, and we have four quadrants around it that give us one of the previously mentioned results.

{| class="wikitable"
|-
| rowspan="4"|[[Image:co-ordquadrants.png|left]]
| [[Image:line06a.gif|left]] $$\picture(100){(50,50){\line(40,45)}}$$,
a positive x and positive y
|-
| [[Image:line06b.gif|left]]$$\picture(100){(50,50){\line(-40,45)}}$$
a negative x and positive y
|-
| [[Image:line06c.gif|left]]$$\picture(100){(50,50){\line(-40,-45)}}$$
a negative x and negative y
|-
| [[Image:line06d.gif|left]]$$\picture(100){(50,50){\line(40,-45)}}$$
a positive x and a negative y
|}

Essentially, what these points boil down to is that anything above the insertion point is a positive on the y axis, anything below is a negative. Anything to the left of the insertion point is a negative while everything to the right is a positive.

{| class="wikitable"
|-
|[[Image:line06e.gif|left]]
| $$\picture(100){(50,50){\line(40,45)}(50,50){\line(-40,45)}(50,50){\line(-40,-45)}(50,50){\line(40,-45)}}$$

The co-ordinate alignment process in TeX is not that good that you can use one set of co-ords as a single starting point for all lines. The layering of each object varies because of the position of the previous object, so each object needs to be exactly placed.

This co-ord structure has a great deal of impact on intersecting lines, parallel lines and triangles.
|}

==Intersecting Lines==

You can set up an intersecting pair easily enough, using the \picture control sequence.

{| class="wikitable"
|-
| [[Image:cfmimetex31.gif|left]]
| $$ \picture(200){(10,0){\line(150,150)} (0,130){\line(180,-180)}} $$

The lines that are drawn can be labeled.

$$ \picture(200){(10,0){\line(150,150)}(0,130){\line(180,-180)}
(0,10){A}(0,135){B}(140,0){C}(140,150){D}(62,80){X}} $$

To produce another image.
| [[Image:cfmimetex32.gif|right]]
|-
| colspan="3" style="text-align: center;"| To which you may want to ask the question:
$$The \ \angle \ of \ AXB \ is \ 72\textdegree. \ What \ is \ the \ value \ of \ \angle BXD? $$
[[Image: cfmimetex32a.gif|center]]

NOTE: Labeling this image, above-right, turned out to be fairly simple. Offsetting points by a few pixels at the start or end points of the lines proved a successful strategy. The X point proved a little more problematic, and took a number of adjustments before getting it right. Experience here will help.
|-
| colspan="2"| With labels the drawing can become a little more like your traditional geometric drawing, but the devil is in the details. The parallel markers need to be placed properly, and that is where experience really comes into it. On lines that are vertical or horizontal, you can get away with using the > or < directly from the keyboard, or the <math>\gg</math> or <math>\ll</math> symbols. In either case, you need to position them properly.

The code:
$$\picture(200){(15,45){\line(170,0)} (15,30){c}(170,28){d}(15,160){\line(170,0)}(15,145){e}(180,143){f}(50,20){\line(110,175)}(58,20){a}(140,185){b}(42,32){\kappa}(53,48){\beta}
(150,165){\kappa}
(90,38){\gg}(80,153){\gg}
}$$
| [[Image:line10.gif|right]]
|}

==Lines and Arcs==

Combining lines and arcs is a serious challenge actually, on a number of levels. For example lets take an arc from the first page on circles.
{| class="wikitable"
|-
| [[Image: cfmimetex21a.gif|left]]
| Fairly innocuous of itself, but when we start to add in elements, it changes dramatically.

$$ \circle(120;90,180) $$
|-
| [[Image: line12.gif|left]]
| $$\picture(150){(75,75){\circle(120;90,180)}(75,75){\line(-70,0)}(75,75){\line(0,75)}} $$
All elements in this drawing start in the same place. Each is layered, and properly placed on the canvas, and using the same co-ord to start makes it easy to control them. No matter the size of the arc, intersecting lines can all be drawn using the centre co-ords of the arc.
|}

==Triangles ==

Of all the drawing objects, it is actually triangles that present the most challenge. For example:

{|
|-
| [[Image:line13.gif|left]]
$$\picture(350){(10,10){\line(0,320)}(10,330){\line(330,0)}(10,10){\line(330,320)}}$$
|This is a simple triangle, one that allows us to establish a simple set of rules for the sides. The vertical always has an x=0 co-ord and the horizontal always has a y=0 co-ord.

In this case with an x value of 330 on the horizontal, and a y value of 320 on the vertical, the hypotenuse should then have a value of x=340, and the y=330, but not so, they actually have an x=330 and a y=320.

There is no need to add the starting point co-ords to the x and y values of the line.
| [[Image:line14.gif|right]]
$$picture(350){(10,10){\line(330,0)}(340,10){\line(0,320)}(340,330){\line(-330,-320)}}$$

|}

This triangle has been developed for a Trigonometry page - but the additional notation should provide insight into how you can use it.

{| class="wikitable"
|-
| [[Image:line16.gif|left]]
| This is a labeled image, but it has an \fbox in it with its little line. With some effort, it could be replaced with two intersecting short lines.
$$\picture(350,150){(25,25){\line(300,0)}(325,25){\line(0,110)}(25,25){\line(300,110)}(309,25){\fbox{\line(5,5)}}
(307,98){\theta}(135,75){\beta}(150,5){\alpha}(335,75){\epsilon}}$$
|}

{| class="wikitable"
|-
| The triangle shows like:
[[Image:trig01.gif|left]]
|We use the different elements of the triangle to identify those things we need to know about a right-angled triangle.

The hypotenuse is always the side that is opposite the right angle. The longest side is always the Hypotenuse.

To identify the other elements of the triangle we look for the sign <math>\theta</math>. <math>\Theta</math> is the starting point for naming the other sides.

The side that is opposite <math>\angle \theta</math> is known as the Opposite.

The side that lies alongside <math>\angle \theta</math> is known as the Adjacent side.

To determine which is which, draw a line that bisects <math>\angle \theta</math> and whatever line it crosses is the Opposite side.
|-
| colspan="2"| The code:
$$ \picture(350,250){(25,25){\line(300,0)}(25,25){\line(0,220)}(25,245){\line(300,-220)}(310,25){\circle(100;135,180)}(20,100){\line(310,-75)} (25,25){\fbox{\line(5,5)}}(25,25){\line(150,150)}(165,140){Hypotenuse}(120,2){Adjacent}(2,80){\rotatebox{90}{Opposite}}(270,40){\theta}}$$
|}

=Matrices=
A Matrix is a rectangular array of numbers arranged in rows and columns which can be used to organize numeric information. Matrices can be used to predict trends and outcomes in real situations - i.e. polling.

==A Matrix==
A matrix can be written and displayed like [[Image: matrices03.gif|A matrix]]

In this case the matrix is constructed using the brackets before creating the array:
$$ M = \left[\begin{array}{ccc} a&b&1 \\ c&d&2 \\ e&f&3\end{array}\right] $$
The internal structure of the array is generated by the &, ampersand, and the double backslash.

You can also create a grid for the matrix.

{| class="wikitable"
|-
|A dashed line
|A solid line
|A mixed line
|-
|[[Image: matrices04.gif]]
|[[Image: matrices05.gif]]
|[[Image: matrices06.gif]]
|-
|$$ M = \left[\begin{array}'''{c.c.c}''' a&b&1 \ '''\hdash''' c&d&2 \ '''\hdash''' e&f&3\end{array}\right] $$
|$$ M = \left[\begin{array}'''{c|c|c}''' a&b&1 \ '''\hline''' c&d&2 \ '''\hline''' e&f&3\end{array}\right] $$
|$$ M = \left[\begin{array}'''{c.c|c}''' a&b&1 \ '''\hline''' c&d&2 \ '''\hdash''' e&f&3\end{array}\right] $$
|}

The command sequences here are the {c|c.c} and \hdash and \hline. The pipe, |, and the full stop determine the line type for the vertical line.

Matrices also respond to other TeX Notation commands such as size and colour.

{| class="wikitable"
|-
|
Colour
| colspan="2"|Size
|-
|[[Image: matrices07.gif]]
|[[Image: matrices08.gif]]
|[[Image: matrices09.gif]]
|-
|$$ '''\blue''' M = \left[\begin{array}{c.c.c} a&b&1 \ \hdash c&d&2 \ \hdash e&f&3\end{array}\right] $$
|$$ '''\fs7''' M = \left[\begin{array}{c.c.c} a&b&1 \ \hdash c&d&2 \ \hdash e&f&3\end{array}\right] $$
|$$ '''\fs2''' M = \left[\begin{array}{c.c.c} a&b&1 \ \hdash c&d&2 \ \hdash e&f&3\end{array}\right] $$
|}

==Creating equal and unequal matrices==
Equal and unequal matrices are simply matrices that either share or not share the same number of rows and columns. To be more precise, equal matrices share the same order and each element in the corresponding positions are equal. Anything else is unequal matrices.

Actually equal and unequal matrices are constructed along similar lines, but have different shapes:

{| class="wikitable"
|-
|Equal Matrix
|An unequal matrix
|-
|[[Image: matrices10.gif]]
|[[Image: matrices11.gif]]
|-
| $$ \left[\begin{array} a&b&1 \ c&d&2 \ e&f&3\end{array}\right] \ = \ \left[\begin{array} 12&11&z \ 10&9&y \ 8&7&x\end{array}\right] $$
| $$ \left[\begin{array} a&b \ c&d \ e&f \end{array}\right] \ \neq \ \left[\begin{array} 12&11&z \ 10&9&y \ 8&7&x\end{array}\right] $$
|}

==Labeling a Matrix==

Addition and subtraction matrices are similar again, but the presentation is usually very different. The problem comes when trying to mix labels into arrays. The lack of sophistication in the TeX Notation plays against it here.

Moodle allows an easy adoption of tables to make it work though. For example:

Bill the baker supplies three shops, A, B and C with pies, pasties and sausage rolls.
He is expected to determine the stock levels of those three shops in his estimation of supplies.

It is better to use the Moodle Fullscreen editor for this, to have a better idea of how the end product will look and to take advantage of the additional tools available. Design decisions need occupy our attention for a while. We need a table of five rows and four columns. The first row is a header row, so the label is centred. The next row needs four columns, a blank cell to start and labels A, B and C. The next three rows are divided into two columns, with the labels, pies, pasties and sausage rolls in each row of the first column and the matrix resides in a merged set of columns there. So first the table:

{| class="wikitable"
|-
| Insert Table - initial properties
| Merge Cells Button
| Advanced Properties
|-
| rowspan="2"|[[Image: matricestable01.png|Table properties]]
| [[Image: matricestable02.png | Merge cells]]
| [[Image: matricestable03.png | Cell properties button]]
|-
| colspan="2"| You may need to look into the Advanced properties setting of the tables and cells to make this work.
|}

This is the immediate result:

[[Image: matricestable04.png | The resulting table]]

While not a very good look, it can be made better by tweaking the table using the advanced settings and properties buttons and then you can tweak the matrix itself.

==Tweaking the Matrix==

[[Image: matricestable05a.png | A tweaked matrix]]

Things are not always as they seem, be aware, the "c" does not stand for "column", it actually stands for "centre". The columns are aligned by the letters l, for left, c for centre and r for right.

Each column is spread across 50 pixels, so the value of 50 is entered into the alignment declaration. The plus sign before the value is used to "propogate" or to force the value across the whole matrix, but is not used when wanting to separate only one column.

To set the rows is a little more problematic. The capital letter C sets the vertical alignment to the centre, (B is for baseline, but that does not guarantee that the numbers will appear on the base line, and there does not appear to be any third value). The plus sign and following value sets the height of all rows to the number given. In this I have given it a value of 25 pixels for the entire matrix. If there were four or five rows, the same height requirement is made.

The order things appear is also important. If you change the order of these settings, they will either not work at all, or will not render as you expect them to. If something does not work properly, then check to make sure you have the right order first.

==An Addition Matrix==

The rule for performing operations on matrices is that they must be equal matrices. For example, addition matrices look like:

[[Image: matricestable06.png | An addition matrix]]

with the results obvious. The code is:

$$\left[\begin{array}{c+50C+25.c.c}
11&14&12 \ \hdash16&12&22 \ \hdash 14&17&15
\end{array}\right] + \left[\begin{array}{c+50C+25.c.c}
60&60&60 \ \hdash 40&40&30 \ \hdash 30&30&30
\end{array}\right] $$

==A Subtraction Matrix==

Similar to an addition matrix in its construction, the subtraction matrix is subject to the same rules of equality.

Using the same essential data, we can calculate the daily sales of each of the shops.

[[Image: matricestable07.png | A subtraction matrix]]

The code is:
$$ \left[\begin{array}{c+50C+25.c.c}
72&95&68 \ \hdash 54&61&65 \ \hdash 48&51&60
\end{array}\right] - \left[\begin{array}{c+50C+25.c.c}
11&14&12 \ \hdash 16&12&22 \ \hdash 14&17&15
\end{array}\right] = \left[\begin{array}{c+50C+25.c.c}
61&81&56 \ \hdash 38&49&43 \ \hdash 34&34&48
\end{array}\right] $$

This code looks more complex than it really is, it is cluttered by the lines and alignment sequences.

==Multiplication Matrices==

Different than the addition or subtraction matrices, the multiplication matrix comes in three parts, the row matrix, the column matrix and the answer matrix. This implies it has a different construction methodology.

[[Image: matrices16.gif | A multiplication matrix]]

And the code for this is:
$$ \begin{array} 10&14&16\end{array} \
\left[\begin{array} 45 \\ 61 \\ 19 \end{array}\right]
\ = \ \begin{array} 450&854&304\end{array} $$

While different, it is not necessarily more complex. For example a problem like:

Bill the baker is selling his product to Con the cafe owner, who
wants to make sure his overall prices are profitable for himself.
Con needs to make sure that his average price is providing sufficient
profit to be able to keep the cafes open. Con makes his calculations
on a weekly basis, comparing cost to sale prices.

With the pies, pasties and sausage rolls in that order he applies them to the cost and sale price columns :

[[Image: matrices17.gif | A multiplication matrix]]

The code for this is:
$$\left[\begin{array} 350&310&270 \end{array}\right] \
\left[\begin{array} \$2.10&\$3.60 \ \$2.05&\$3.60 \ \$1.90&\$3.10 \end{array}
\right] \ = \ \left[\begin{array} \$735.00&\$1260.00 \ \$635.50&\$1116.00 \
\$513.00&$\837.00 \end{array}\right] $$

==How to wrap long MathJax equations==
As [https://moodle.org/mod/forum/discuss.php?d=389730 described by Christopher Sangwin]:

See [http://docs.mathjax.org/en/latest/output/linebreaks.html this documentation].

Add

CommonHTML: { linebreaks: { automatic: true } },
"HTML-CSS": { linebreaks: { automatic: true } },
SVG: { linebreaks: { automatic: true } }

to "filter_mathjaxloader | mathjaxconfig" in the filter settings: Dashboard > Site administration > Plugins > Filters > MathJax Seems to do the trick.

==See Also==
* [[Mathematics_tools_FAQ]]
* [[MathJax_filter]] - available in Moodle 2.7 and later
* [[TeX notation filter]] To turn on the TeX Notation
* [[DragMath equation editor]]
* [[Chemistry notation using mhchem]]

[[Category:Mathematics]]

Atto editor

2021-07-14T13:24:23Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Editing text}}
==The Atto text editor==

The Atto text editor (sometimes referred to as the 'HTML editor') has many icons to assist the user in entering content. Many of these icons and functions should be familiar to anyone who uses a word processor.

Some examples of where you will see the text editor include: Editing Section headings, description of an activity, writing an answer to a quiz question or editing the content of many blocks.

The default text editor in Moodle is the Atto editor, built specifically for Moodle. There is also a [[TinyMCE editor]] and a plain text editor.

Text editors can be enabled, disabled or a different one set to default from ''Administration > Site administration > Plugins > Text editors > Manage editors''. The order of priority may also be specified here.

If more than one text editor is enabled, users can select their preferred editor via their preferences page in the user menu (top right).

{{MediaPlayer | url = https://youtu.be/fEtGcVz0pzE | desc = }}

==Atto features==

===Image copy and paste===

In Moodle 3.9 onwards, images can be copied from anywhere and pasted into the Atto editor. For example, you can take a screenshot, copy it to your clipboard and then paste it into the Atto editor.

===Image drag and drop===

If your browser allows it (and if it does, you will see a message at the top of your screen when the editing is on) you can add images into the Atto editor simply by dragging them from your computer:

[[File:Attodragdrop29.png|thumb|600px|center|Drag an image directly into the editor]]

===Autosave===

Text typed into the Atto editor is automatically saved if you leave the page. The default of 60 seconds may be changed by the administrator in ''Site administration>Plugins>Text editors>Atto HTML editor>Atto toolbar settings.'' If the user accidentally closes the tab or otherwise leaves the form without submitting, the text in the editor will be restored next time he opens the page. To discard a restored draft, the user needs to cancel the form or press the "Undo" button in the editor.
[[File:AtttoAutosave.png|thumb|600px|center]]

==Atto editor toolbar==

[[File:Attotopline1382.png]]

Atto Row 1 default buttons

{| class="wikitable"
|-
|-
| 1. Expand
| 2. Style
| 3. Bold
| 4. Italic
|-
| 5. Bulleted list
| 6. Numbered list
| 7. Add link
| 8. Unlink
|-
| 9. Add image
| 10. Add smiley (if enabled)
| 11. Add media
| 12. Record audio
|-
| 13. Record video
| 14. Manage embedded files
| 15. H5P

|}

[[File:Attobottomline.png]]

Atto Row 2 default buttons

{| class="wikitable"
|-
|-
| 1. Underline
| 2. Strikethrough
| 3. Subscript
| 4. Superscript
|-
| 5. Align left/centre/right
| 6. Decrease/increase indent
| 7. Equation editor
| 8. Special character
|-
| 9. Table
| 10. Clear formatting
| 11. Undo/redo
| 12. Accessibility checker
|-
| 13. Screenreader helper
| 14. HTML/code view
|
|}

===Manage embedded files===
This allows users to add, delete or override files embedded in the current text area, for example in a label or topic summary. (It complements the [[Embedded files repository]])

[[File:26embeddefiles2.png|thumb|400px|center]]

===Accessibility checker===

One of the tools available in the text editor is an automated [[Accessibility|accessibility]] checker which checks for some common errors in the text. These are usually things in the way the text is constructed that can prevent all users from having equal access to information and functionality. The list of problems that the accessibility checker looks for is:

* Images with missing or empty alt text (unless they have the presentation role)
* Contrast of font colour and background colour meets [https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines WCAG AA guidelines]
* Long blocks of text are sufficiently broken up into headings
* All tables require captions
* Tables should not contain merged cells as they are difficult to navigate with screen readers
* All tables should contain row or column headers

===Screenreader helper===

Screen readers basically treat a content editable region like a text box - which is wrong, because it can contain images, links and more.

The screen reader helper provides additional information about the currently selected text (e.g. is it bold), as well as a listing of any images or links in the text.

===Equation editor===

If either the [[MathJax filter|MathJax]] or the [[TeX notation filter|TeX notation]] filters are enabled (in ''Administration > Site administration > Plugins > Filters > Manage filters'') then an equation editor button is provided in the toolbar for launching the equation editor.

===Table editor===

If the administrator has enabled the extra settings for the Atto table editor (see below) then border styling, sizing and colours are available when creating a table:

[[File:AttoTableRevised.png|center|thumb|center]]

==Keyboard shortcuts==

The following keyboard shortcuts will work in the Atto text editor in most browsers. Note that for many of these commands to work you need to either click in the text editor or select content in the text editor.

{| class="wikitable"
|-
! Windows Command
! Mac Command
! Function
|-
| Ctrl + c
| ⌘ + c
| Copy
|-
| Ctrl + v
| ⌘ + v
| Paste
|-
| Ctrl + Shift + v
| ⌘ + Shift + v
| Paste without formatting (very useful)
|-
| Ctrl + x
| ⌘ + x
| Cut
|-
| Ctrl + z
| ⌘ + z
| Undo (careful - can undo a lot of text and doesn't always work)
|-
| Ctrl + y
| ⌘ + y
| Redo
|-
| Ctrl + a
| ⌘ + a
| Select all
|-
| Double-click
| Double-click
| Select word
|-
| Triple-click
| Triple-click
| Select line
|-
| Ctrl + f
| ⌘ + f
| Find on page
|-
| F3
| F3
| Find next
|-
| Shift + F3
| Shift + F3
| Find previous
|-
| Ctrl + b
| ⌘ + b
| Bold
|-
| Ctrl + i
| ⌘ + i
| Italics
|-
| Ctrl + u
| ⌘ + u
| Underline
|-
| Ctrl + k
| ⌘ + k
| Insert/edit link
|-
| Ctrl + Right arrow
| ⌘ + Right arrow
| Move to the end of the next word
|-
| Ctrl + Left arrow
| ⌘ + Left arrow
| Move to the end of the previous word
|-
| Ctrl + Shift + Right arrow
| ⌘ + Shift + Right arrow
| Select the next word or letter
|-
| Ctrl + Shift + Left arrow
| ⌘ + Shift + Left arrow
| Select the previous word or letter
|-
| Ctrl + Shift + Home
| ⌘ + Shift + Home
| Select from the cursor to the beginning of the page
|-
| Ctrl + Shift + End
| ⌘ + Shift + End
| Select from the cursor to the end of the page
|-
| Ctrl + Home
| ⌘ + Home
| Move to the beginning of the page
|-
| Ctrl + End
| ⌘ + End
| Move to the end of the page
|-
| Ctrl + Backspace
| ⌘ + Backspace
| Delete word or letter to the left
|-
| Ctrl + Delete
| ⌘ + Delete
| Delete word or letter to the right
|-
| Ctrl and +
| ⌘ and +
| Zoom in (not specific to the editor, but very useful)
|-
| Ctrl and -
| ⌘ and -
| Zoom out (not specific to the editor, but very useful)
|-
| Ctrl and 0
| ⌘ and 0
| Reset zoom (not specific to the editor, but very useful)
|}

<span style="font-size:80%">Source: [https://confluence.royalroads.ca:8443/pages/viewpage.action?pageId=47778173 Jason 1keddie, Royal Roads University (Creative Commons Attribution-ShareAlike)]</span>

==Site administration settings==

===Toolbar settings===

The administrator can specify which plugins to display and in which order from ''Administration > Site administration > Plugins > Text editors > Atto HTML editor > Atto toolbar settings''.
[[File:atto-plugins.png|thumb|center|450px|Atto Plugins]]

====Toolbar config table====
The toolbar is split into groups of related buttons. The format for the config setting is:

groupname1 = button1, button2, button3
groupname2 = button1, button2, button3

The group names on the left have no effect on how the toolbar works; they just need to be different for each button (and no spaces please). The list of buttons says which button goes in which group and in what order. The exact word to insert here for each button is listed in the "Toolbar config" column above.

The reason there are names for the groups is that it helps to make you think about how to group the buttons sensibly and not just stick new buttons in random locations. Ie. all the buttons in the "files" group interact with the file picker in some way

===Adding extra buttons===

Extra plugins (for example the contributed plugin 'Font color') may be added (once installed) by typing the toolbarconfig term into the toolbar config table.

[[File:toolbarconfig.png]]

Here for example are the available colours when 'fontcolor' is added:

[[File:fontcolor.png]]

The icons are displayed in related groups and the administrator can decide how many groups to display in the default collapsed state of the toolbar (that is, how many groups to display on Row 1).

====Autosave frequency====
Text is automatically saved at regular intervals so it may be restored when the user returns to a form they had previously left. This setting allows the administrator to specify the time between autosaves. The default is one minute.
==== Non default Atto plugins ====
Not all plugins are enabled by default and the administrator of each site should give careful thought as to which plugins they choose to enable for their users. Here are some things to consider before enabling the non-default plugins:

===== Emoji picker =====
An emoji picker button may be added by typing 'emojipicker' into the toolbar config table.
[[File:toolbar with emoji picker.png|thumb|Toolbar with emoji picker button]]
To add the emoji picker button to the top row:

# Enter the line <code>emoji = emojipicker</code> under the line <code>files = image, emoticon, media, managefiles, recordrtc, h5p</code>
# Go to 'Collapse toolbar settings' and change 'Show first (n) groups when collapsed' to 6 and save changes.

===== Emoticons =====
The emoticon plugin inserts text representations of the emoticons in the content. The emoticon filter is responsible for converting these text sequences into proper smiley images. The emoticon filter is not enabled by default, which is why the emoticon plugin for Atto is not enabled by default.

===== No-auto link =====
In general, the more plugins are added to the Atto toolbar, the harder it becomes to find specific plugins. Because the no-auto link plugin is not felt to be widely used it is not enabled by default.

===== Right to left =====
Because this plugin is only useful for courses where text needs to be written in a mixture of both "left to right" and "right to left" languages, it is not enabled by default.

==== Moodle plugins directory ====

There are more plugins available for Atto than just those included in a default install.
See the [https://moodle.org/plugins/browse.php?list=category&id=53 Moodle plugins directory] for additional plugins.
Some example plugins include the following:

==== Background colour / Font colour ====
While these are very popular plugins, there are downsides to enabling their use on a site. Firstly - user specified colours may conflict visually with the site colours chosen by the theme designer. Even if the colours of the content do not conflict with the colours of the current theme, if the theme is changed in future, or the content is reused on a different site conflicts may be introduced. There are 2 possible types of conflicts, the first is just a visually unappealing combination of colours, the second is a combination of colours that may produce text that is hard to read for some people. It is preferable if the theme designer uses some interesting colours that meet the accessibility standards required for the site in the theme for the site, and the person creating the content simply uses the proper heading levels (for example) to make use of those styles.

===== Cloze editor for Atto=====
[[Cloze editor for Atto|This]] is a plugin for easily making [[Embedded Answers (Cloze) question type]] questions inside the standard Moodle Atto text editor.

===== Toggle preview =====
This plugin allows you view the content as it would be seen by a reader.

===== Chemistry plugins =====
There are a number of chemistry plugins that support chemistry equations and structures.

===== Text import plugins =====
There are a number of plugins that support importing text from other sources.
The [https://moodle.org/plugins/view/atto_pastespecial Paste special] plugin minimises the amount of superfluous HTML markup
included when pasting content from an external editor such as Microsoft Word.

The [https://moodle.org/plugins/view/atto_wordimport Word Import] plugin (beta) supports importing an entire Word document,
including embedded images.

===Equation editor settings===

Equation editor commands may be removed, added or reordered in ''Administration > Site administration > Plugins > Text editors > Atto HTML editor > Equation editor settings''.

[[File:equationeditor.png]]

===Table editor settings===
Styles, colours and sizes for tables and their borders may be enabled from ''Administration > Site administraton >Plugins > Test editors > Atto HTML editor > Table settings.''

==See also==

* [[Text editor FAQ]]
* [[Embedded files repository]]
* [[Word count quick guide]] - Word count is a plugin for the [[Text editor|Atto text editor]] which is used to create content within Moodle. This plugin enables the author of text, such as a student, to check how many words and letters are in a piece of text.

[[Category:Site administration]]
[[Category:Language teaching]]

[[de:Text-Editor]]
[[es:Editor Atto]]
[[fr:Éditeur de texte]]

Development:Scheduled Tasks Proposal

2021-07-14T13:24:22Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Moodle 2.0}}

== Introduction ==

This proposal is meant both to provide a replacement for the moodle cron job, and provide a means to schedule once off tasks to be run outside of the user's request lifecycle.

== Terminology ==

* '''Subtask''' an individual piece of cron processing that should be run (equivalent to forum_cron now, or maybe even smaller)
* '''Moodle cron instance''' a cron.php process

== Rationale ==

The moodle cronjob currently delegates all scheduling to each subtask that is run - for example, the forum cron is responsible for checking when it last run, and making decisions about whether or not it should be run again. This sort of decision process should be centralised, and individual cron subtasks should be called by the central controller.

Additionally, there is not any central locking of subtasks. At the moment, some subtasks that expect that they might take a long time to run implement their own locking (for example statistics), but it's not centralised. Each moodle cron instance runs to completion, no matter how long it takes, and it processes tasks in the order that they're programmed, regardless of if there are any other moodle cron instances running, that might be processing sub tasks in parallel

The existing events API seems like it should provide a way to schedule tasks to be run outside of a user's request cycle, but in reality this just adds to the existing cron problem. We need to have a way in Moodle to schedule once off tasks to be run "at the next available time" which are picked up by cron. This can be used to process the event queue, but also for some code to just register a new once off cron event "on the fly" and be picked up on the next run.

Finally, we need to be able to run non-related tasks in parallel so that the entire moodle queue isn't held up by single long running jobs.

== Goals ==

* Centralised locking for '''all''' tasks
* A way consistent for '''all plugin types''' to register with Moodle (at installation/upgrade) when they want their jobs run
* More sophisticated scheduling rather than just intervals in seconds (eg every sunday at 11pm or similar) based on unix cron
* An administration screen in Moodle to allow site administrators to adjust the scheduling of individual tasks
* An easy way for core and module code to schedule a once off task to be run as soon as possible

== Approach ==

=== Plugin cron registration ===

Each plugin will be able to provide a db/tasks.php (alongside access.php and events.php etc) that lists all the cronjobs that it wants to have run. This will look something like the following:

<code php>
<?php
$tasks = array(
array(
'function' => 'yourmodule_cron_somedescription',
'minute' => '*',
'hour' => '*',
'day' => '*',
'month' => '*',
'dayofweek' => '*',
'description' => 'langstringkey', // this must correspond to get_string('langstringkey', 'yourmodule');
),
);

</code>

The fields are the same as normal unix cron, with the exception that you cannot use 3 letter words for the month and day of week fields like you can for unix cron. The following is straight from the unix manpage about cron:

<pre>

field allowed values
----- --------------
minute 0-59
hour 0-23
day of month 1-31
month 1-12 (or names, see below)
day of week 0-7 (0 or 7 is Sun, or use names)

A field may be an asterisk (*), which always stands for ``first-last''.

Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen.
The specified range is inclusive. For example, 8-11 for an ``hours'' entry specifies
execution at hours 8, 9, 10 and 11.

Lists are allowed. A list is a set of numbers (or ranges) separated by commas.
Examples: ``1,2,5,9'', ``0-4,8-12''.

Step values can be used in conjunction with ranges. Following a range with ``/<number>''
specifies skips of the number's value through the range. For example,
``0-23/2'' can be used in the hours field to specify command execution every other hour
(the alternative in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22''). Steps
are also permitted after an asterisk, so if you want to say ``every two hours'', just use ``*/2''.

</pre>

The unix crontab manpage goes on to say that one can use 3 letter words in the month and dayofweek fields (eg Sun or Feb). I don't think this is necessary for our implementation.

=== Database ===

'''scheduled_tasks:'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|plugintype
|varchar(50)
|plugintype - should match the path-style declarations in get_plugin_types (eg question/type, not qtype). Will be null for core tasks.
|-
|pluginname
|varchar(50)
|name of the plugin. Will be null for core tasks.
|-
|callfunction
|varchar(200) (unique)
|the function to call. Must be unique, as it will be used for the locking.
|-
|lastruntime
|int(10)
|unix timestamp
|-
|nextruntime
|int(10)
|unix timestamp
|-
|blocking
|int(1)
|0 or 1 - whether this task, when running, blocks everything else from running.
|-
|minute
|varchar(25)
|
|-
|hour
|varchar(25)
|
|-
|day
|varchar(25)
|
|-
|month
|varchar(25)
|
|-
|dayofweek
|varchar(25)
|
|-
|customised
|integer(1)
|0 or 1 - whether this time differs from what is in code
|}

This table is for all the normal scheduled regular tasks. The time fields are intially populated when a plugin is installed or upgraded, but can be overridden by an administrator, which sets the "customised" flag to 1. If the administrator later decides to revert their customisation, the original code-values are repopulated into this table.

'''scheduled_onceoff_tasks:'''

{| border="1" cellpadding="2" cellspacing="0"
|-
|'''Field'''
|'''Datatype'''
|'''Comment'''
|-
|id
|integer
|sequence
|-
|plugintype
|varchar(50)
|plugintype - should match the path-style declarations in get_plugin_types (eg question/type, not qtype). Will be null for core tasks.
|-
|pluginname
|varchar(50)
|name of the plugin. Will be null for core tasks.
|-
|callfunction
|varchar(200) (unique)
|the function to call. Must be unique, as it will be used for the locking.
|-
|nextruntime
|int(10)
|unix timestamp
|-
|customdata
|text
|any data or serialised information
|-
|blocking
|int(1)
|0 or 1 - whether this task, when running, blocks everything else from running.
|}

This table is for the once off tasks, which are run and then deleted. There isn't a unique constraint on 'callfunction' in this table, because the same once off task may be scheduled twice before the first one is processed. In this case, the named lock will be obtained using a combination of callfunction and the id.

The original database specification had extra custom fields in the main scheduled_tasks table, that the cronjobs could insert information into, called custom1 and custom2 and so on. I've removed these from this specification until such time as we have a solid use-case for them. It is certain that we need it for the once off tasks, however, but in this case I think it's better to just have a text field that can either contain a single value, or a serialised blob of information.

The original spec also had a priority field, but this has been removed after the conversation in Jizerka, which led to the proposal to just let some jobs block all others, rather than prioritising individual tasks. '''This decision may be later reverted''' especially for once off tasks, where some may be really urgent.

=== Locking ===

Penny and Tim originally thought that the best approach was to try and do something that would cause an exception to be thrown - for example, try to insert into a row that had a unique constraint on it, and catch the exception. However, this will cause far too much noise in the logs. Matt Oquist came up with a different approach in MDL-21110. We could potentially change this slightly to allow alternative implementations, by means of an abstract class and factory method (this was suggested by Sam Marshall), but probaby isn't needed for the initial implementation.

=== Black magic ===

Cron.php will need to be rewritten to look something like this:

<code php>
<?php

while ($nexttask = cron_get_next_task()) {
cron_call_function($nexttask);
}

</code>

With some black magic to hand out the next task, which does:

* Checks how long the existing process is allowed to run for
* Figures out if there's already a "blocking" task running
* Figures out the next task that's scheduled
* Tries to get a lock on it
* Returns that task

== Unresolved issues/ideas ==

* It might be nice at some point to find a way to allow different subtasks to run on different servers by designation. This could be eventually added in to the administration screens as an extra setting (IP address)
* We obviously need some way to avoid different tasks trampling on eachother. We ran through a number of ideas already, from differentiating between read/write operations, to having dependencies or conflicts between tasks, to having each task say which database tables it uses. Finally we decided it would be best to just have some tasks that are able to simply block all others from being run. Anything to do with authentication and enrolment must block other tasks from running, as otherwise there could be the problem of for example, forum posts being emailed out just before someone is unenrolled from a course.
* When the first cron in a long time is running, we should lock the entire cron and let it run to completeness, because the order is really important then. This means that there also needs to be some global lastcronruntime flag somewhere (like in the config table)

== Psuedo code proposal ==
Moved [[Development_talk:Scheduled_Tasks_Proposal|to the talk page]]

== Audit of current cron ==

{| class="wikitable"
|-
! Main section
! Subtask
! Frequency
! Notes
|-
| session_gc
|
| every run
|
|-
|mod/assignment
|plugins (none)
|every minute
|
|-
|mod/assignment
|message submissions
|every minute
|checks last run time
|-
|mod/chat
|update chat times
|every five minutes
|
|-
|mod/chat
|update_events
|every five minutes
|
|-
|mod/chat
|delete old chat_users and add quits
|every five minutes
|
|-
|mod/chat
|delete old messages
|every five minutes
|
|-
|mod/data
|
|every minute
|no _cron function (includes file unnecessarily)
|-
|mod/forum
|mail posts
|every minute
|checks last run time
|-
|mod/forum
|digest processing
|every minute
|
|-
|mod/forum
|delete old read tracking
|every minute
|
|-
|mod/scorm
|reparse all scorms
|every five minutes
|does hourly checking
|-
|mod/wiki
|delete expired locks
|every hour
|-
|blocks/rss_client
|update feeds
|every five minutes
|
|-
|quiz/report/statistics
|delete old statistics
|every run
|
|-
|admin/reports
|none
|every run
|
|-
|language_cache

|every run
|
|-
|remove expired enrolments
|
|every run
|
|-
|main gradebook
|lock pending grades (*2)
|every run
|
|-
|main gradebook
|clean old grade history
|every run
|has a TODO to not process as often
|-
|event queue
|
|every run
|potentially large
|-
|portfolio cron
|clean expired exports
|every run
|potentially large
|-
|longtimenosee

|20%
|
|-
|deleteunconfirmedusers
|
|20%
|
|-
|deleteincompleteusers
|
|20%
|
|-
|deleteoldlogs
|
|20%
|
|-
|deletefiltercache
|
|20%
|
|-
|notifyloginfailures
|
|20%
|
|-
|metacourse syncing
|
|20%
|
|-
|createpasswordemails
|
|20%
|
|-
|tag cron
|
|20%
|
|-
|clean contexts
|
|20%
|
|-
|gc_cache_flags
|
|20%
|
|-
|build_context_path
|
|20%
|
|-
|scheduled backups
|
|daily (admin defined)
|
|-
|make rss feeds
|
|every run
|
|-
|auth/mnet
|keepalives
|every run
|
|-
|auth/mnet
|delete old sessions
|every run
|
|-
|auth/ldap
|sync users
|custom
|not scheduled (external cronjob)
|-
|auth/cas
|sync users
|custom
|not scheduled (external cronjob)
|-
|auth/db
|sync users
|custom
|not scheduled (external cronjob)
|-
|enrol/authorize
|clears old data
|daily (admin defined)
|
|-
|enrol/authorize
|notifies administrators of old data
|daily (admin defined)
|
|-
|enrol/authorize
|process orders & email teachers
|every run
|
|-
|enrol/flatfile
|read file and sync users
|every run
|!?!
|-
|enrol/imsenterprise
|read file and sync users
|every run
|!?!?!
|-
|enrol/manual
|notify people of pending unenrolments
|daily
|
|-
|statistics
|
|daily (admin defined)
|huge
|-
|grade/import
|none
|every run
|
|-
|grade/export
|none
|every run
|
|-
|grade/reports
|none
|every run
|
|-
|fetch blog entries
|
|every run
|
|-
|file gc
|
|(optional) daily, else every run?
|
|-
|local cron
|
|
|
|}

== Tasks ==

* Audit all existing cronjobs (done)
* Implement the locking code, either Matt's or something similar and write robust tests for it (this will be hard to test perhaps - can we test race conditions using simpletest?)
* Write the black magic that hands out the next task to be run for a given cron process
* Rewrite cron.php to use the black magic
* Migrate all the existing cronjobs to the new system
* Write screens to allow administrators to reschedule tasks
* Write code to transfer between unix-cron-syntax and user-friendly syntax (and vice versa)
* Write code to capture requests to schedule once off tasks
* Update portfolio code to use once off tasks rather than events API
* Evaluate integration of event API to once off tasks
* Test thoroughly

The above tasks are now in MDL-25499 as sub-tasks to implement this proposal.

== TODO ==

Development:Cohorts

2021-07-14T13:24:22Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Work in progress}}
{{Infobox Project
|name = Cohorts
|state = Work in progress
|tracker = MDL-21781
|discussion = n/a
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
}}
{{Moodle 2.0}}

=Goals=
Site-wide groups (aka cohorts) is one of the most requested missing features.
# Simplify manual enrolments - instead of enrolling students one by one, it would be possible to enrol a cohort with single click.
# Cohort enrolment plugin - new enrolment plugin synchronising users in cohort with enrolments in a course (including role assignment and group membership)
# Synchronisation with external systems - some external systems do not know the actual courses, they only contain some user groups, at present we do not have a simple way to reuse these groups in Moodle.
# Partially replace meta courses
# Replace category enrolments - category enrolments have major design issues and are not compatible with incomming enrolment changes.

=DB tables=

Table ''cohort'' definition of site-wide groups (aka cohorts)

{| class="wikitable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''contextid'''
| int(10)
|
| foreign key, references context.id
|-
| name
| char(254)
|
| human readable cohort name
|-
| '''idnumber'''
| char(100)
|
| unique identifier of the cohort, can be used in external systems
|-
| description
| text
|
| longer description
|-
| descriptionformat
| int(2)
|
| text format
|-
| component
| char(100)
|
| component name of a plugin responsible for assignment of users (ex: auth_ldap, etc.), NULL means manual assignments
|-
| timecreated
| int(10)
|
| timestamp, creation date
|-
| timemodified
| int(10)
|
| timestamp, last modification
|}

Context specified can be system or course category level, defining of cohort a course context would not make much sense.

Table ''cohort_members'' stores cohort members

{| class="wikitable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''cohortid'''
| int(10)
|
| foreign key, references cohort.id
|-
| '''userid'''
| int(10)
|
| foreign key, references user.id
|-
| timeadded
| int(10)
|
| timestamp, when added
|}

=New capabilities=
* moodle/cohort:assign - add/delete members (only for manual assignment cohorts with source == null)
* moodle/cohort:manage -add/delete/move cohorts
* moodle/cohort:view - view membership and use cohort elsewhere

Context id defined in cohort table is used for access control only, the cohort may be actually used in any context (this may happen when moving courses, categories or cohorts).

=User interface=
# Cohort edit link in CONTEXT_SYSTEM and each CONTEXT_COURSECAT- most probably from the settings block
# Option for manual cohort enrolment - part of new enrolment UI
# New UI in cohort enrolment plugin
# New options in group creation UI
# New options for sync with external groups in auth or enrol plugins

=Implementation steps=
# add db tables and cohort membership UI
# add option to assign role to all cohort users (one time only, no sync)
# enrolment rewrite
# cohort enrolment plugin

=Upgrade=

Cohorts are designed to replace course category enrolments because the new enrolment plugin is not compatible with this.

=See also=
* [[Obsolete:Enrolment rewrite and role tweaks proposal]]
* [[Development:New permissions evaluation in 2.0]]
* [[Development:New permission overriding UI]]
* [[Development:New enrolments in 2.0]]

[[Category:Roles]]

Regular Expression Short-Answer question type

2021-07-14T13:24:21Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Infobox plugin
|type = question type
|entry = https://moodle.org/plugins/pluginversions.php?plugin=qtype_regexp
|tracker = https://github.com/rezeau/moodle-qtype_regexp/issues
|discussion = https://moodle.org/plugins/qtype_regexp
|maintainer = [[user:Joseph Rézeau]]
|float = right
}}{{Questions}}
===The RegExp Short Answer Question===

* '''IMPORTANT NOTE'''
** The RegExp Short Answer question described in this documentation page is a 3rd-party plugin, which allows you to create questions for the '''''Quiz''''' activity. It is ''different'' from the "Use regular expressions" option in the '''''Lesson''''' module.
** The documentation for the "Use regular expressions" option in the '''''Lesson''''' module is to be found at: [https://docs.moodle.org/en/Short_answer_analysis Short answer analysis].

Like the Short Answer question, the RegExp Short Answer question expects the respondent to answer an "open" question with a word or a short phrase. However, the RegExp system gives you access to a more powerful system for ''analysing the student's answers'' with the aim of ''providing more relevant immediate feedback''.
The RegExp Short Answer question is meant to be used with questions requiring '''natural language''' answers. This question type is not well-suited to questions requiring mathematical, scientific, programming "languages".

===Correct answer matching a regular expression pattern===

It is not possible to give complete examples of the vast possibilities offered by this system, and the following are just some possibilities.

===='''Example 1.'''====

Suppose your question was "What are the colors of the French flag?". In the Answer 1 box you would type the "best" answer, e.g. "it's blue, white and red". For more details, see [[#firstcorrect|First correct answer]] below.

*In the Answer 2 box you would type this regular expression: "it's blue, white(,| and) red" (quotes should not be typed, of course).
* If [[#casesensivity|Case sensivity]] is set to "No", this will match any of those 4 responses:
it's blue, white, red
it's blue, white and red
It's blue, white, red
It's blue, white and red

===='''Example 2'''.====

Question: "What are blue, red and yellow?".
* Answer 1: "they are colours".
* Answer 2: "(|they('| a)re )colou?rs".
* This will match any of those 6 responses:
colours
colors
they're colours
they're colors
they are colours
they are colors

'''''Note'''''.- The beginning of this regular expression "(|they('| a)re )" will match either nothing or "they're " or "they are ". In "colou?r", the question-mark means: the preceding character (or parenthesized group of characters) zero or one time; it is used here to match British English as well as US spelling.

===='''Example 3.'''====

Question: "Name an animal whose name consists of 3 letters and the middle letter is the vowel ''a''".
* Answer 1: "cat"
* Answer 2: "[bcr]at".
* This will match: bat, cat or rat.

'''''Note'''''.- In Regular Expression syntax, the inclusion of characters between square brackets means than ANY of those characters can be used. So, in the above example, the regular expression "[bcr]at" is the exact equivalent of "(b|c|r)at". Be careful NOT to include the pipe character as separator in your [...] regular expressions. For instance, "[b|c|r]at" will NOT WORK CORRECTLY.

===='''Example 4.'''====

The 'permutation' feature (introduced in regexp version '''2012102900''' for Moodle 2.3+)

Question: "What are the colours of the French flag (in any order)".
* Answer 1: "it's blue, white and red"
* Answer 2: <nowiki>"it's [[_blue_, _white_(,| and) _red_]]".</nowiki>
Upon saving the question, Answer 2 will be automatically re-written as Answer 2b:

it's (blue, white(,| and) red|blue, red(,| and) white|white, red(,| and) blue|white, blue(,| and) red|red, blue(,| and) white|red, white(,| and) blue)

and it will match all the following answers:
it's blue, white, red
it's blue, white and red
it's blue, red, white
it's blue, red and white
it's white, red, blue
it's white, red and blue
it's white, blue, red
it's white, blue and red
it's red, blue, white
it's red, blue and white
it's red, white, blue
it's red, white and blue

'''''Note'''''.- This 'permutation feature' has been asked quite a few times by regexp users. It is definitely ''not'' possible to obtain it by using standard Regular Expressions syntax.

It is possible (but tedious) to write a regular expression including all the possible permutations - as in Answer 2b above - but the ''ad hoc'' syntax I am offering makes it easier to write... provided you strictly adhere to that syntax!

Include within double square brackets the part of the Answer which will contain 'permutable' words or phrases. You are actually allowed to have a maximum of 2 such sets of 'permutable' words or phrases. But you cannot embed one set within another!

Then, use pairs of underscores (the _ character) to delimit each 'permutable' word or phrase. You can still use any of the accepted Regular Expressions characters, as explained here, in your Answers which contain one (or two) such sets of 'permutable' words or phrases. If your Answer does not contain an even number of underscores, an Error warning will be displayed upon clicking the Show Alternate Answers button or when trying to Save your question.

===='''Example 5.'''====

Another 'permutation' example

Question: "Quote the English proverb that is an encouragement to hard, diligent work."

* Answer 1: "Early to bed and early to rise makes a man healthy, wealthy and wise"
* Answer 2: "Early to <nowiki>[[_bed_ and early to _rise_]], makes a man [[_healthy_, _wealthy_ and _wise_]]</nowiki>"

Upon saving the question, Answer 2 will be automatically re-written as Answer 2b:

Early to (bed and early to rise|rise and early to bed) makes a man (healthy, wealthy and wise|healthy, wise and wealthy|wealthy, wise and healthy|wealthy, healthy and wise|wise, healthy and wealthy|wise, wealthy and healthy)

and it will match all the following answers:

Early to bed and early to rise makes a man healthy, wealthy and wise
Early to bed and early to rise makes a man healthy, wise and wealthy
Early to bed and early to rise makes a man wealthy, wise and healthy
Early to bed and early to rise makes a man wealthy, healthy and wise
Early to bed and early to rise makes a man wise, healthy and wealthy
Early to bed and early to rise makes a man wise, wealthy and healthy
Early to rise and early to bed makes a man healthy, wealthy and wise
Early to rise and early to bed makes a man healthy, wise and wealthy
Early to rise and early to bed makes a man wealthy, wise and healthy
Early to rise and early to bed makes a man wealthy, healthy and wise
Early to rise and early to bed makes a man wise, healthy and wealthy
Early to rise and early to bed makes a man wise, wealthy and healthy

===Escaping metacharacters===

====Definition====
In the Regular Expressions syntax, a number of special characters or ''meta characters'' have special functions; but it is possible to force these special characters to be interpreted as normal (or ''literal'') characters by preceding them with a so-called ''escape'' character, the backslash "\".
Below is a (partial) list of those ''meta characters'':

'''. ^ $ * ( ) [ ] + ? | { } \ /'''

====In Accepted Answers====

* '''Accepted Answers''' are Answers which have a grade greater than zero, i.e. are ''totally'' (grade = 100%) or ''partially'' (grade > 0% < 100%) ''correct Answers''.

In those Answers, if you need to use one or more ''meta characters'' for their ''literal'' value, you '''must''' ''escape'' them (i.e. precede them with a backslash).

'''Example 1.-''' If you want to accept the answer "This computer costs 1000$ in the US.", you must write the Answer as "This computer costs 1000\$ in the US\.".

'''Example 2.-''' If you want to accept the answer "Desktop computers are (usually) more powerful than laptops.", you must write the Answer as "Desktop computers are $usually$ more powerful than laptops\.".

* You can mix metacharacters that have a special function with others that have a literal value, within one Answer.
'''Example 3.-''' If you want to accept both answers "Computers are (usually) cheaper than cars." and "Computers are (usually) less expensive than cars.", you must write the Answer as "Computers are $usually$ (cheaper|less expensive) than cars.".
* In the '''Accepted Answers''' boxes you can only enter regular expressions which can generate a finite number of sentences. That is why you will not be allowed to use some ''meta characters'' which match a potentially infinite number of sentences.
* List of ''meta characters'' which you '''can''' use for their RegExp functions:

'''( ) [ ] ? |'''

* List of ''meta characters'' which you '''cannot''' use for their RegExp functions, and can only be used for their ''literal'' value (and must be ''escaped'').

'''. ^ $ * + { } \ /'''

* The question mark (?) can be used either for its RegExp function OR, if escaped, for its ''literal'' value.

'''Example 4.-''' "Do you like Jack(ie)?\?" will accept both "Do you like Jack?" and "Do you like Jackie?".

====In Incorrect Answers====

* '''Incorrect Answers''' are Answers which have a grade equal to zero (or None).
When you write those Incorrect Answers, you can use the whole range of ''meta characters'' for their special function value:

'''. ^ $ * ( ) [ ] + ? | { } \ /'''

For examples of use, see '''Detecting missing required words or character strings''' below.

====Answers Validation====

When you validate your Question, the question engine checks the validity of your expression, according to the features explained above. If an error is found, an ERROR message is displayed above the erroneous Answer(s) and you cannot save the Question until that error has been corrected.

The validation system also checks that your parentheses and square brackets are correctly balanced.

'''Note.-''' The faulty Answer text is "underlined" with the list of errors, as shown below.

[[Image:Errors_en.jpg]]

===Detecting missing required words or character strings===

This is a powerful feature of the RegExp question type. It will analyse the student's answer for words that are required for the answer to be correct. There are 2 ways to do this.
* Use what is called "negative lookahead assertion" in regular expressions syntax: '''^(?!.*required.*)'''
* or use an ''ad hoc'' pseudo-syntax provided in RegExp (an initial double hyphen): '''--.*required.*'''.
In the examples below, we shall be using the 'ad hoc' RegExp pseudo-syntax, and sometimes give the "negative lookahead assertion" equivalent for anyone interested.

Any Teacher Answer which begins with a double hyphen will analyse the student’s response to find out whether the following string is present or absent. If present, the analysis continues to the next question; if absent, the analysis stops and the relevant feedback message is displayed.

'''Example 4. ''' Question "What are the colors of the French flag?".

* Teacher Answer 2: --.*blue.*
* Sample student Response: "it's red and white"
* Feedback 2: The color of the sky is missing!

Here, the . (dot) stands for “any character” and the * (asterisk) means “preceding special character repeated any number of times”. The Teacher Answer 2 regular expression above means: check whether the character string "blue", preceded with anything and followed by anything is absent from the student's answer. Please note that the use of the asterisk is different in Moodle's "normal" Short Answer question type and in the RegExp question type.

Actually, this syntax is not sufficient to track the absence of the word "blue" in a student's answer such as "it's blueish, white and red". To make sure that we want to track the absence of "blue" as a word(and not just as part of a word), we must use the metacharacter \b which is an anchor which matches at a position that is called a "word boundary". Hence the new version of our Example 4:

'''Example 4b. ''' Question "What are the colors of the French flag?".

* Teacher Answer 2: --.*\bblue\b.*
* Sample student Response: "it's blueish, white and red"
* Feedback 2: The color of the sky is missing!

'''Note.-'''
Using the "negative lookahead assertion" syntax mentioned at the beginning of this section, Teacher Answer 2 would look like this:
* Teacher Answer 2: '''^(?!'''.*\bblue\b.*''')'''

'''Example 5.''' Question: "Name an animal whose name consists of 3 letters and the middle letter is the vowel ''a''".
* Teacher Answer: "--^[bcr].*". '''OR''' * Teacher Answer: "--^(b|c|r).*".
* Sample student Response: "dog"
* Feedback: "Your answer should start with one of these letters: b, c or r"

'''Note.-'''
In regular expressions syntax, the caret ^ stands for "beginning of character string to be matched", while the dollar sign $ stands for "end of character string".

'''Example 6.''' Question "What are the colors of the French flag?".

* Teacher Answer: "--.*(blue|red|white).*"
* Sample student Response #1: "It's black and orange."
* Feedback: "You have not even found one of the colors of the French flag!"
* Sample student Response #2: "It's blue and orange."
* Feedback: None, the analysis continues to the next Teacher Answer expression.

'''''Explanation'''''.- The regular expression looks for a missing word among those listed between brackets and separated by the | sign. As soon as one of those words is found, the "missing condition" is considered false, and the response analysis continues to the next Answer's regular expression.

'''Note.-'''
Using the "negative lookahead assertion" syntax, Teacher Answer would look like this: '''^(?!.*(blue|red|white).*)'''

'''Example 7.''' Question "What are the colors of the French flag?".

* Teacher Answer: "--.*('''&&'''blue'''&&'''red'''&&'''white).*"
* Sample student Response #1: "It's blue and orange."
* Feedback: "You have not found all the colors of the French flag".
* Sample student Response #2: "white blue red".
* Feedback: None, the analysis continues to the next Teacher Answer expression.

'''''Explanation'''''.- The regular expression looks for a missing word among all of those listed between brackets and separated by the && double character combination. Only if all of those words are present, will the "missing condition" be considered false, and the response analysis continue to the next Answer's regular expression. Please note that the list of parenthesized words must begin with the && character sequence.

'''Note.-'''
Using the "negative lookahead assertion" syntax, Teacher Answer would look like this: '''(^(?!.*(blue).*)|^(?!.*(white).*)|^(?!.*(red).*))'''

===Editing a regular expression question===

[[Image:regexp settings 01.jpg]]

====Help Button Mode====

Selecting a mode other than ''None'' will display a button to enable the student to get the next letter or word or punctuation mark (including the very first letter or word).

''The "Word or Punctuation" help mode is a new feature starting in Moodle 3.1.
''

In ''Adaptive mode'' the button displayed will say "Buy next letter" or "Buy next word" or "Buy next word or punctuation" according to the mode selected by the teacher. For setting the "cost" of buying a letter or word, see the ''Penalty for incorrect tries and Buying a letter or word'' settings further down the Edit form.

In ''Adaptive No penalty'' mode the button displayed will say "Get next letter" or "Get next word" or "Get next word or punctuation".

By default the Help button mode value is set at '''None'''. The Help button will only be available to quizzes that have their '''Question behaviour''' mode set to ''Adaptive'' or ''Adaptive (no penalties)'' as it does not make sense to enable the Help button for non-adaptive tests.

====Show alternate answers to student====
Show all correct alternative answers to student when on review page? If there are a lot of automatically generated correct alternative answers, displaying them all can make the review page quite long. So, you may wish to ''not'' display all those alternative correct answers. The first correct answer will always be displayed, under the label "The best correct answer is:"

====<span id="firstcorrect">First correct answer</span>====

For Answer 1 you must enter an answer text which a) is the "best" possible answer; b) is '''not''' a regular expression or - more exactly - ''will not be interpreted as a regular expression'' but "as is" and c) has a Grade value of 100%. You will notice that when you create a new RegExp question the Grade value for Answer 1 is already automatically set at 100% and cannot be changed.

Note.- There are two ways to enter an answer containing meta characters, according to whether this is Answer 1 or any of the subsequent Answers. Exemple question: how much did your computer cost?

Answer 1: It cost $1,000.

Answer 2: It cost (me )?\$1,000\.

In Anwer 1 you just type the expected answer "as is". The text in Answer 2 will be interpreted as a regular expression, and thus you need to escape the two meta characters (the $ sign and the end-of-sentence full stop). Note that here I have added the optional pronoun "me".

====Other answers====

Any answers with a Grade higher than 0% must be entered as valid regular expressions ''which can yield acceptable alternative answers'' (regardless of the Grade being less than 100%).

For example, you cannot enter the following Answer with a grade greater than zero:

.*blue, white(,| and) red.*

The reason is that this expression would accept as correct (with a non-null grade) an infinity of answers, many of which would be incorrect, e.g.: "My hat it blue, white, red and orange", "The French flag is blue, white, red, black and nice" etc.

If you try to do so, validation of your question will fail and an error message will be displayed to tell you where you went wrong.

This means that some regular expressions, which are perfectly valid and would correctly analyse the student's (correct) answer are not recommended. The only case where they would work is a) if your question's '''Display Hint Button''' is set at No and b) your quiz '''Adaptative Mode''' is set at No. This means that you must ''not'' enter as an answer with a grade higher than 0% a regular expression beginning with a double hyphen "--", used for detecting missing character strings.

====Show/Hide alternate answers====

When you are creating (or modifying) a RegExp question, you may want to make sure that all the alternative correct answers that you have created in the Answers fields will work. You can click the '''Show alternate answers''' button to calculate and display all the correct answers in the form you are editing. This may take quite some time on your server, depending on the number and complexity of the regular expressions you have entered in the Answer fields!

On the other hand, it is the recommended way to check that your "correct answers" expressions are correctly written. Here is an example.

Please remember that only Answers regular expressions with a score greater than zero will be used to calculate those alternative answers.

Please note that clicking the '''Show alternate answers''' button will perform an analysis of all the regular expressions you entered in the Answers field. If a syntax error is detected at this stage, the alternative correct answers will ''not'' be displayed, and an ''ad hoc'' error message will displayed above the faulty regular expression.

[[Image:showhidealternateanswers.jpg]]

===Automatic formatted extra feedback===
Please note that the RegExp question can be used in any '''Question behaviour''' mode. However, it is advised to create quizzes containing only RegExp questions or containing other types of questions, but ''preferably'' if the quiz's '''''Question behaviour / How questions behave''''' setting is set to ''Adaptive mode'' (with or without penalty).

When a student (or teacher in Preview Question mode) submits a response to a RegExp question, 3 types of feedback messages are displayed (in Adaptive mode).

* (line 3) The standard correct/incorrect Quiz message (plus the colour associated with either state).
* (line 2) The Feedback message entered by the question creator for each Teacher Answer.
* (line 1) An extra feedback system is automatically provided, displaying the student's submitted response, with the following format codes:
** the beginning of the student's submitted response which best matches one of the Alternate Answers is displayed in blue;
** any words from the submitted response which are present in the potential Alternate Answers following the initial correct part submitted (correct but misplaced words) are displayed on a green background;
** any words not present in the potential Alternate Answers following the initial correct part submitted (Wrong words) are displayed on a red background.
The meaning of those colours is explained below the feedback with the 2 labels "Wrong words" and "Misplaced words".

''Please note that the colour scheme has been changed starting with the Moodle 3.1 version of RegExp.''

[[Image:regexp04.jpg]]

===Feedback given by the Help button===

Each time a student clicks the '''Buy/Get next letter/word/punctuation''' button to buy/get a letter/word/punctuation mark, that letter, word or punctuation mark is added to their response. The last line of the feedback zone shows the following information: added letter/word; penalty cost (if applicable); total penalties so far (if applicable). Note that if the total of penalties exceeds 1 (i.e. 100%), that total is displayed in red.

When the teacher views the quiz results, on the ''''Review Attempt'''' pages, ''''Response history'''' section, the response history shows ''Submit (with a request for help)'' with the response states before and after the letter/word/punctuation mark was added.
----
[[Image:regexp03.jpg]]

===Display right answers===

If your Quiz settings ''Review options'' are set to display the Right answer (During the attempt or Immediately after the attempt etc.), and your question's ''Show alternate answers to student'' setting is set to '''Yes''', when the student has submitted his attempt, and is reviewing his answers, all of the possible answers will be displayed, as shown in this screenshot. Correct responses with a grade < 100% are also listed, with their grade value.

Please note that the ''teacher'' will always be able to see that "other accepted answers" section when reviewing the Quiz answers.

[[Image:23 correct responses.jpg]]

===In the Mobile App===
Starting with the Moodle 3.5 version, RegExp includes code for the Moodle Mobile App. If you access a quiz with the mobile app that contains RegExp questions it will be automatically loaded as a remote add-on.

[[Image:regexp05.jpg]]

Similar to the ''short answer'' core question type instructions, "Normally the answer box appears below the question text. However, if you include five or more underscores in the text, the input box will be placed there." This inline input feature has recently been made available to the Moodle mobile version for "short answer" questions. It is now available for the "regexp" question type as well.

If you enter this regexp question text: The ____________ sat on the white mat.

This is what it will look like in a moodle mobile quiz:

[[Image:2019-06-04_18-40-30.jpg]]

===Inserting RegExp sub-questions in Cloze type questions===

{| class="wikitable"
|-
!Important notice
|-
|
The RegExp question type is '''''not''''' recognized by the standard Moodle '''Cloze''' question type. If you want to use it you'll have to replace 2 files (''renderer.php'' and ''questiontype.php'') on your ''<yourmoodle>/question/type/multianswer'' with the hacked files available from the links below. '''UPdated 26 NOVEMBER 2020'''.
Compatible with Moodle 3.10.

https://raw.githubusercontent.com/rezeau/moodle_multianswer_regexp_compatible/master/questiontype.php

https://raw.githubusercontent.com/rezeau/moodle_multianswer_regexp_compatible/master/renderer.php

|}

Syntax for inserting RegExp sub-questions in Cloze type questions.

Use '''REGEXP''' or shorter '''RX''' coding for questions which ignore case

* The colors of the French flag are {:REGEXP:=blue, white and red#Correct!}.
* The colors of the French flag are {:RX:=blue, white and red#Correct!}.

Will accept "blue, white and red" as a correct answer as well as "Blue, White and Red"

use '''REGEXP_C''' or shorter '''RXC''' coding for questions in which case matters
* The colors of the French flag are {:REGEXP_C:=blue, white and red#Correct!}.
* The colors of the French flag are {:RXC:=blue, white and red#Correct!}.

Will not accept "Blue, White and Red" as a correct answer (wrong capital letters).

Please note that, as explained above, the very first answer ''must'' be Graded 100% (in Cloze type question syntax, all correct is either '''=''' or '''100%''') and it must ''not'' be a regular expression.

A more complete example. If you enter the following in the text of a Cloze question:

The colors of the French flag are {:REGEXP:=blue, white and red#Very correct indeed!~--.*\bblue\b.*#The color of the sky is missing!~--.*(blue|red|white).*#You have not even found one of the colors of the French flag!}.

and click the ''Decode and verify the question text'' button, you will see this:

<code php>
Question definition
{:REGEXP:=blue, white and red#Very correct indeed!~--.*(blue|red|white).*#You have not even found one of the colors of the French flag!~--.*\bblue\b.*#The color of the sky is missing!}
Default mark
1
Answer
blue, white and red
Grade
1
Feedback
Very correct indeed!
Answer
--.*(blue|red|white).*
Grade
0
Feedback
You have not even found one of the colors of the French flag!
Answer
--.*\bblue\b.*
Grade
0
Feedback
The color of the sky is missing!</code>
[[Image:regexp_in_cloze_question.jpg]]

Please note that the syntax of the sub-questions inside a Cloze-type question must be followed exactly and that you must never ever copy and paste any question text from e.g. a word-processor into the Cloze-type question editing window. Quite often Cloze-type questions yield errors because extraneous blank spaces, new lines, or any odd formatting character has made its way into the question text.

Note that the ''Hint'' button is not available for a RegExp question embedded in a Cloze-type question.

==See also==
====Downloads====
* Download [http://moodle.org/plugins/view.php?plugin=qtype_regexp the Regexp question type] from the Moodle Plugins repository.
* IMPORTANT : Starting with the 2.2 version of REGEXP, if you want the Help feature, you must also download and install the following 2 "question behaviours" from the Moodle Plugins repository: [http://moodle.org/plugins/view.php?plugin=qbehaviour_regexpadaptivewithhelp RegExp Adaptive mode with Help] and [http://moodle.org/plugins/view.php?plugin=qbehaviour_regexpadaptivewithhelpnopenalty RegExp Adaptive mode with Help (no penalties)].

====Installation====
-------------------------------
If you have downloaded the zip archive from the new moodle.org plugins page

1.- Unzip the zip archive to your local computer.

2.- This will give you a folder named "regexp".

3.- GO TO STEP 4 below
---

If you have downloaded the zip archive from https://github.com/rezeau/moodle-qtype_regexp ('''for latest developments''')

1.- Unzip the zip archive to your local computer.

2.- This will give you a folder named something like "rezeau-moodle_qtype_regexp-ff8c6a1". The end of the name may vary.

3.- ***Rename*** that folder to "regexp".

---

4.- Upload the regexp folder to <yourmoodle>/question/type/ folder.

5.- Visit your Admin/Notifications page so that the new question type gets installed.

====Learn more about regular expressions====

*[http://www.regular-expressions.info/tutorial.html Regular Expressions Tutorial] A complete introduction to the topic.
*[http://www.regexplanet.com/simple/index.html Regular Expression Test Page] Test your regular expressions on a variety of "answers".

====See also these other Moodle question types based on regular expressions====
* [[Pattern-match question type]]
* [[Preg question type]]

[[Category:Quiz]]
[[Category:Questions]]
[[Category:Contributed code]]

[[fr:question/type/regexp]]
[[es:Tipo de pregunta respuesta corta de expresión regular]]
[[de:Fragetyp Kurzantwort vom Typ regulärer Ausdruck]]

Development:Styling and customising the dock

2021-07-14T13:24:19Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Template:Themes}}{{Moodle 2.0}}The dock is a new addition to Moodle 2.0, it allows the user to move blocks from the flow of the page onto a special bar that is displayed in a constant position on the side of the page by default.
This document looks at how to style the dock using CSS, as well as how to customise or manipulate it within JavaScript.

==Styling the dock==
Styling the dock is really no different to styling anything else within a web site however there are a couple of things that may slow you down and reading the following document may help you in your understanding of how the dock works and how you should go about styling it.

The following items are things that you should be aware of before starting to style the dock:
# When a block is docked the dock attempts to ensure that existing styles for the block are still applied by adding the standard block '''.block_''blockname'''''. Because of this trick we don't need to look at the actual content of a docked item it will always be the same as the block.
# The dock remembers what blocks are docked by saving the user's choices within the database using AJAX calls. This can be looked at to minimise display jumping within a theme's layoutfile. Read on to learn how.
# The dock uses CSS classes to transition the different states. These CSS classes control things such as the whether the dock is visible, whether the panel is visible, and how we know which item is being viewed. Read the section on [[#State_classes|state classes]] to learn more about these.
# The structure of the dock is built entirely by JavaScript. Because of this you will need a tool such as FireBug to inspect it within a page as it won't be there until JavaScript has run.
# Although the base theme doesn't support the dock it does contain some core CSS to structure the dock by default.

So lets get started and look at the structure.
===The structure of the dock===
[[Image:Dock.structure.201005.png|300px|thumb|Dock structure]]
The first image to the left graphically describes the hierarchical structure of the dock. The first thing you will notice about this image is that it doesn't describe what each element is for. It is just to illustrate the html structure without at styles or transformation.

So what are the important elements here?

; div#dock.dock.dock_left_vertical : This is the bar on the left. Positioned by default to be fixed position in the top left hand corner of the screen and 30px wide.
; div.dockeditem_container : This box contains all of the buttons which when clicked or hovered over will display the docked item. Or more technically causing the docked item panel to be shown.
; div#dock_item_x.dockeditem : This represents one of possibly several docked item buttons containing the title of the docked item. There are two things to note about this element: First it is repeated for every docked item. Second the x within the id is the item instance and should not be used for styling.
; div.controls : This contains any special controls for the dock and by default is displayed at the bottom of the dock. As of Moodle 2 Preview Release the only control here is to undock all docked items.
; div#dockeditempanel : This is the panel in which docked items are shown. Although it is within the dock is it positioned outside of the page relative to the button for the item it is currently showing. This element is based loosely off the YUI3 overlay.

===The layout of the dock===
[[Image:Dock.layout.201005.png|300px|thumb|Dock layout]]
The second image on the left shows the layout of these elements within the standard theme.

'''So what has gone on here?'''
First up ignore the bright colours and margins. I have put these colours in simply to highlight everything and ensure there is space between elements so I can show them apart.

; div#dock : So immediately you notice that the dock is in the top left of the screen and the is fixed width. This is achieved by setting a strict with of 30px and setting the position of the ''#dock'' to fixed. The reason that everything is within the one ''#dock'' element is because it makes positioning everything very simple, now that we have set the position of ''#dock'' we don't need to worry about anything other than the panel which we'll get to shortly. You should also note that because of the strict width and position you need to be careful when applying styles to this element as it can have nasty effects on everything else.

; div.dockeditem_container : Next you should notice that the ''.dockeditem_container'' doesn't extend to the bottom of the dock. Because there is not special positioning here it is behaving as div's normally do and this is the perfect place to really start styling your dock.

; div.controls : After that within the structure we have ''div.controls''. This element is positioned absolutely at the bottom of the dock, is 100% wide (so the full width of the dock) and uses ''text-align:center'' to ensure that the controls are centred.

; div.dockeditem : Simply representing a button that can be hovered over or clicked to display the docked item the only important thing to note about this is that you should change the cursor to a pointer so that it is clear you can interact with it.

; div#dockeditempanel : After ''#dock'' this is the most serious element in the dock. This element will contain the docked item and needs to positioned to the left of the dock and at the same height as the title of the item that is being displayed. Luckily you don't need to worry about the top position of the element that will be automatically adjusted by JavaScript however you will need to push the element to the left. This can be done easily by setting the position of the element to relative, and then setting left to 100%. Note you shouldn't style this element unless you know what you are doing, like the main dock element the smallest change can cause some terrible effects.

; div.dockeditempanel_container : This element is there specifically to give you the themer an easy place to start styling the panel.

; div.dockeditempanel_hd : This element contains the title of the docked item plus controls to undock or close it.

; div.dockeditempanel_bd : Contains is the main content area for the panel.

===State classes===
There are several state classes that the dock makes use of to achieve things such as the visibility of the dock, visibility of the panel, and which item is active.
The following table illustrates where these state classes are used.
{| class="wikitable"
! Element
! Class
! Description
! Default CSS
|-
|body
|has_dock
|This class is added to the body element when the dock is visible.
|Margin-left: 30px
|-
|#dock
|nothingdocked
|This class is added to the dock when there is nothing docked.
|visibility: hidden; display: none;
|-
|#dock
|.dock_''position''_''style''
|A special class is added to describe the docks desired position e.g. dock_left_vertical
|
|-
|.dockeditem
|activeitem
|This class is added to the item that is currently being shown.
|Change the background colour
|-
|.dockeditem
|firstdockitem
|This class is added to the first dock item.
|
|-
|.dockeditem h2
|filterrotate
|Added when the title is being rotated by an IE filter [Internet Explorer only]
|
|-
|#dockeditempanel
|dockitempanel_hidden
|Added to the panel when it is not being shown.
|visibility: hidden; display: none;
|-
|#dockeditempanel
|oversized_content
|Added when the panel required scrolling to show everything.
|Set the overflow method
|}

===Layout file changes===
There is only one thing that you need to make sure of within your layout files if you are creating your own. You need to add the class ''block-region'' to all of the block region div's as shown below.
<code php>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</code>
Whilst there is nothing else you '''need''' to change within your layout files there one other thing that you may want to do.

Because the dock is loaded entirely by JavaScript you will notice a visual jump on the page if all of the blocks within a region have been docked. This is because the dock shrinks sections that have been completely docked so that they don't wast page space.

Within you layout files you can check whether a section has been completely docked and then if it has set the body classes so that it is shrunk when the page is delivered.

I'm going to assume that you have all read the [[Development:Themes 2.0 creating your first theme]]. If you haven't go read it now.
So now that you've created your first theme think back to the code you wrote at the top of your layout files that checks whether a page has block regions pre and post. The code was as follows:
<code php>
$hassidepre = $PAGE->blocks->region_has_content('side-pre', $OUTPUT);
$hassidepost = $PAGE->blocks->region_has_content('side-post', $OUTPUT);
</code>
Right below these two lines we are going to add two more:
<code php>
$showsidepre = ($hassidepre && !$PAGE->blocks->region_completely_docked('side-pre', $OUTPUT));
$showsidepost = ($hassidepost && !$PAGE->blocks->region_completely_docked('side-post', $OUTPUT));
</code>
What we have here is two variables that tell use whether we should show the block regions pre and post. The verbal interpretation of this string is to say ''We will show this side if this side has content and if there is at least one block that has not been docked.'' and we repeat it for each side.

Now that we know for each region that it has content and that we should show it we need some way to tell the page what block regions to show.
This is achieved by adding special classes to the body element of the page as follows:
; side-pre-only : This gets added to the body if we only want to show the block region pre.
; side-post-only : Just like side-pre-only except for the post region.
; content-only : This gets added if don't want to show either block region.
By default we want to show both regions so we don't need to add any class for this.
So how to do this in PHP?
<code php>
$bodyclasses = array();
if ($showsidepre && !$showsidepost) {
$bodyclasses[] = 'side-pre-only';
} else if ($showsidepost && !$showsidepre) {
$bodyclasses[] = 'side-post-only';
} else if (!$showsidepost && !$showsidepre) {
$bodyclasses[] = 'content-only';
}
</code>
What we have here is three if-else statements, of which either one or none will be true.
# The first if statement says if we want to show the pre region but not the post region add the class ''side-pre-only''
# The second if statement says if we want to show the post region but not the pre region add the class ''side-post-only''
# The third class says if we don't want to display either region add the class ''content-only''

Now that we know which class we want to add to the body element we need to do so. This can be done as follows:
<code php>
<body id="<?php echo $PAGE->bodyid ?>" class="<?php echo $PAGE->bodyclasses.' '.join(' ', $bodyclasses) ?>">
</code>
You'll notice this is very similar to the body tag you wrote in your first theme, however we have added
<code php>
join(' ', $bodyclasses)
</code>
This php command simply concatenates each body class putting a space between each.

Now the final thing to do is make sure that we don't show a block region if we don't have content for it. This can be done by adding if statements around each block region as follows:
<code php>
<?php if ($hassidepre) { ?>
<div id="region-pre" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<?php } ?>

<?php if ($hassidepost) { ?>
<div id="region-post" class="block-region">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
<?php } ?>
</code>
For each if statement we are saying ''If this region has content display it.'' You'll notice that here we are using ''$hasside...'' instead of ''$showside...'' this is because we want to add them if they have content even if they won't be shown. Otherwise the dock won't be able to find them and you simply won't see the block.

Having made the above changes if you now look at the layout files for the base theme you start to notice that they are looking very similar and indeed they are. If at any point you get stuck or don't know how to proceed have a look at the base themes layout files and see how its done there.

===The core CSS===
As mentioned in the key points at the start of this document the base theme although not supporting the dock does contain structural CSS that ensure the dock is functional on all themes that choose to support it.
Lets look at the CSS within ''theme/base/style/dock.css'', this is the core structural CSS for the dock.
<code css>
/* Put a margin on the body if the dock is shown */
body.has_dock {margin-left:30px;}
</code>
Well this is very simple, if the dock is being shown apply a 30px margin to the body. This is done to ensure that the dock doesn't overlap the body.

<code css>
/** For the dock itself */
#dock {width:30px;position:fixed;top:0px;left:0px;height:100%;background-color:#FFF;border-right:1px solid #000;z-index:11000;}
#dock.nothingdocked {visibility: hidden;display:none;}
</code>
These two rules style the dock itself. Note the second rule is only applied when nothing is docked in which case we will hide the empty dock.

<code css>
#dock .dockeditem .firstdockitem {margin-top:1em;}
#dock .dockeditem .dockedtitle {border-bottom:1px solid #000;border-top:1px solid #000;cursor:pointer;}
#dock .dockeditem .dockedtitle h2 {font-size:0.8em;line-height:100%;text-align:center;}
#dock .dockeditem .dockedtitle .filterrotate {margin-left:8px;}
</code>
The four rules above style the buttons that will show the docked items. Each docked item has one. The styles being used here arn't doing anything to special other than setting the cursor to pointer so that it is recognised as an actionable element.

<code css>
#dock .controls {position:absolute;bottom:1em;text-align:center;width:100%;}
#dock .controls img {cursor:pointer;}
</code>
Very simply this bit of CSS. It is positioning the controls for the dock at the bottom centre of the dock.

<code css>
/** For the panel the docked blocks are shown in */
#dockeditempanel {min-width:200px;position:relative;z-index:12000;left:100%;}
#dockeditempanel.dockitempanel_hidden {display:none;}
</code>
These two lines are applied to the docked item panel's base element and are VERY important to the operation of the dock. They ensure that when shown the panel is top the left of the dock and that when it is not being displayed it is not visible.

<code css>
#dockeditempanel .dockeditempanel_content {background-color:#fff;border:1px solid #000;z-index:12050;}
#dockeditempanel .dockeditempanel_bd {overflow:auto;width:auto;}
#dockeditempanel .dockeditempanel_bd .block_docked {margin:10px;}
#dockeditempanel .dockeditempanel_hd {border-bottom:1px solid #000;text-align:right;}
#dockeditempanel .dockeditempanel_hd h2 {display:inline;margin:0;padding-right:1em;}
#dockeditempanel .dockeditempanel_hd .commands {display:inline;}
#dockeditempanel .dockeditempanel_hd .commands img {margin-right:2px;vertical-align:middle;}
</code>
The above lines of CSS are used to style the internal content of the panel. Note the styles for the block will be applied as if it were not docked.

And that is it!

Whilst things don't look to difficult when styling things if you don't think carefully about where you are applying styles you can quickly dig yourself a big hole. I would suggest going slowly at first when applying more styles and making sure you don't apply too many styles to the base elements #dock and #dockeditempanel.

==Customising the dock==
This section of the document looks at how to customise the dock using JavaScript.

It was recognised early on during the development of the dock that it probably won't suit everyone's needs, nor would it appeal to everyone. Because of this during development and the frequent revisions that were occurring during Moodle 2.0s development there was always a focus on ensuring the dock was customisable and that someone with a bit of time on their hands and a good knowledge of JavaScript could hack it to bits and make it into the tool they desired.

This document doesn't go into the full details of how to customise the dock but should get anyone keen started quickly. Those who fear JavaScript should leave now!

===Getting started===
The dock is written to make use of YUI3 and all the functionality that it has to offer, the main dock object both looks for specific callback functions and adds manages and fires several important events. At the same time it is also object orientated JavaScript which has the advantage in JavaScript of allowing subsequent JavaScript events to redefine methods of the object.

This allows you the theme designer to write JavaScript to customise the dock in two fashions. The first through events and callbacks. The second through manually overriding the methods the dock uses.

We will look into these two methods in the subsequent sections of this document, for the time being what you need to learn about is the JavaScript structure of the dock.

First all of the code for the dock within Moodle 2.0 is located within the file '''moodle/blocks/dock.js''' and can be viewed online through the CVS repository[http://cvs.moodle.org/moodle/blocks/dock.js?view=markup]

There are three main objects that get used for the dock:
# First up is of course the dock, which is namespaced to M.core_dock.dock. It is instantiated only once per page and is essentially a static object that manages and operates the dock plus everything on it.
# Second is a generic block class. Every block on the page gets instantiated as a generic block unless it has a more specific class (that should extend the generic block class). This generic block class is responsible for moving a block between the dock and its normal block position. It is namespaced to M.core_dock.generic_block.
# The third class is the dock item class which is used to represent an item on the dock. It is responsible for showing the item when required and handles the events that the dock + user trigger. I can hear you asking now why not just add this functionality to the generic block class? because this keeps it open for things other than blocks to be docked.

As well as the above three classes there are some important class objects and properties that you should also be aware of as you may want to work with them when customising the dock.
; M.core_dock.Y : Is a YUI instance for use with the dock.
; M.core_dock.nodes.dock : Is the façade for the dock itself (#dock) and is a YUI3 Node instance.
; M.core_dock.getPanel() : This will return the panel that is used to display docked item within. It is stored locally through M.core_dock.nodes.panel however as it is not initialised until it is required you should always use the getPanel method.

The following are other important notes about the dock that you should read and understand before customising the dock.
# The dock emulates the YUI3 '''on''' method for listening to events. Because the dock requires initialisation which may occur through module dependencies we needed a method of exposing the dock to events prior to initialisation and this is it. It ensures that if you attach events to the dock before it is initialised everything still works fine.
# Both the dock and the item class inherit from Y.EventTarget and publish several events.
# The dock is designed to work both on old and modern browsers and as such there are several places where we branch based on browser and version.
# The generic block class should never be added to for the needs of a single block. Only things that are generic to all blocks should be added to this class. Independent needs should be handled by creating a block specific class that extends the generic block class. The navigation and settings blocks do this currently.

===Extending the dock through events===
Under construction

===Using custom methods for the dock===
Under construction

==More information==

* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 how to make the dock horizontal]] - Modifying the dock to make it horizontal.

admin/repository/nanogong

2021-07-14T13:24:19Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

=Nanogong plugin=

The Nanogong plugin allows audio-only recording inside the Moodle repositories. The wav files are stored into Moodle using the File API. The sound files can be recorded using the ImaACPCM or Speex codecs. The recorded files and the recording applet are available in all places where the repository is used to select files.

After installing the plugin, you can select the codec used and the quality of the sound for the site-wide recording instance. This instance will be shared by all users of your site (because it only handles recording, and File API handles the rest).

==Audio format==

This option allows you to select the codec used for recording sound.

ImaADPCM stands for International Multimedia Association (IMA) Adaptive Differential Pulse Code Modulation (ADPCM). It is a lossy compression mechanism that compresses data recorded at various sampling rates. The compression ratio obtained is relatively modest, but it is very fast to encode and decode.

Speex is an Open Source/Free Software patent-free (part of the GNU Project) audio compression format designed for speech. Speex is well-adapted to Internet applications and provides useful features that are not present in most other codecs. The design goals have been to make a codec that would be optimized for high quality speech and low bit rate.

==Sampling rate==

This option allows you to select the sampling rate used for recording sound. The actual numeric value associated with each level depends on the audio format in use.
{| class="wikitable"
|-
!Level
!ImaADPCM sampling rate (Hz)
!Speex sampling rate (Hz)
|-
|Low quality
|8000
|8000
|-
|Medium quality
|11025
|16000
|-
|Normal quality
|22050
|32000
|-
|High quality
|44100
|44100
|}

File upload size

2021-07-14T13:24:18Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Installing Moodle}}
==Upload file size restrictions==

Probably the most frequently asked question on moodle.org is "How do I increase the upload file size limit?" The changes that need be made are the same in all versions of Moodle, just in different OS' they need be made in different places. Upload file sizes are restricted in a number of ways and each one in this list restricts the following ones:

# Server level
# Moodle site level
# Course level
# Activity level

This is a contentious issue, mainly because you might think that it should be set inside the Moodle. Unfortunately, this is not so, these are environment issues that need to be set in the server and PHP folders, Moodle cannot work outside itself.

==Physical access to Server==
These instructions assume you have full physical and administrative access to your server. If you are using a hosted server then you will probably need to look into other ways to increase your file upload size.

There are positives and negatives to both methods below. If you modify the php.ini file then the changes will effect all php applications on your server. Since PHP5 you can only have one php.ini file on your server. The php.ini method will work with all web servers though. The .htaccess method will only effect the folder and all subfolders that it is placed in, but you must have certain settings enabled in Apache.

==Restricting the File size - how it works==
The Host may set a limit on the maximum file upload size in the Server environment, which you may override if the Host allows you to. PHP has a setting that it uses to limit the size of the file that it handles in upload. The Host has set that figure in the php.ini based on their particular perceptions and their clientele need. This size appears in Moodle in the '''Site administration > Security > Site security settings > Maximum uploaded file size''' drop-down combo box. You can change this at any time to suit your site need. In the Course Settings page, there is also a further restriction that can be made. At no time can the Course setting over-ride the Site setting, nor can the Site setting over-ride the php.ini setting, which cannot over-ride the Server setting. The only exception to this rule is that you can manipulate both the Server and the PHP settings, and how to do that is described below.

==Modifying the php.ini file==
These instructions show you how to change the file upload size by editing your php.ini file.

For the most part these instructions amount to the following.
In the file /etc/php5/apache2/php.ini you need to change "post_max_size", "upload_max_filesize" and "max_execution_time" to values that suit your needs using whatever editor you are used to.

Below are some line by line instructions for various installations of Moodle.

====Ubuntu Linux Instructions====

These instructions assume that you have installed the standard Moodle package, PHP 5 and Apache 2 via apt-get and left it all as a default install. If you have compiled yourself I presume that you will know where your php.ini files are!
NB As latest version of '''PHP is now 7.2+''' you may need to find the file. If you run phpinfo() this should give you the correct location which will be something like: /etc/php/7.3/apache2/php.ini

You need to edit the following three settings in your php.ini file located at: /etc/php5/apache2/
Here are a set of instructions to follow line by line.

*Type "sudo nano /etc/php5/apache2/php.ini"
*Press Ctrl and W and type "post_max_size"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "upload_max_filesize"
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl and W and type "max_execution_time"
*Change the value to 600
*Press Ctrl and O
*Press Ctrl and X
*Type sudo apachectl restart

[http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size NGINX] system administrators should also add "client_max_body_size XXXm;" to the "http" section of their nginx main configuration file. ([https://rtcamp.com/tutorials/php/increase-file-upload-size-limit/#change-in-nginx-config see more info]) if you have SSL, that will require you to set the above for the SSL ''server'' and ''location'' too.

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

====XAMPP on Mac Instructions====

These are instructions for how to do this for Moodle on a Mac using the [http://download.moodle.org/macosx/ XAMPP sample download package available]. (This is not for a OS X production server.)

* Close down Apache and MySQL if they are running via the XAMPP Control app and close the XAMPP Control app
* Open Finder and go to Applications
* Navigate down and open the folder ''XAMPP'' / ''xamppfiles'' / ''etc''
* Open the file ''php.ini'' with TextEdit (or another plain text editor)
* Search for the ''post_max_size'' setting and up this from 128M (the default) to more; 500M is the maximum
* Do the same for ''upload_max_filesize'' (make the numbers the same)
* Search for the ''max_execution_time'' setting and up this to 300 (or more if you get timeouts on uploads)
* Save the php.ini file
* restart Apache and MySQL as usual

Note: You may get a "permission denied" error when saving the php.ini file unless you are logged in with admin access to your Mac. To work around this, you can set the ''/etc'' directory in which the php.ini file is located to be writable temporarily. For how to do that, see [http://answers.yahoo.com/question/index?qid=20090115235753AA4DtJ0 here] or [http://www.ehow.com/how_2314896_fix-permissions-mac-os-x.html here].

====Windows XP and Server 2003 Instructions====

These instructions presume that you have downloaded the latest PHP 5.3.x Windows zip package and extracted it to C:\PHP. If you have installed PHP to another location then change all references to "C:\PHP" to the location you installed PHP too.
{| class="wikitable"
|[[Image:lightbulb.png]]
|Download and install any text editor that can save the file in a UTF-8 format, [http://www.crimsoneditor.com Crimson Editor] is one such, NotePad++ is another, use that instead of either Wordpad or Notepad! The issue is that WordPad or Notepad will include hidden characters that may not be compatible with the requirements of PHP.
|}

*Open C:\PHP
*Right Click the '''php.ini''' file in this folder and choose "Open with..." selecting your editor of choice.
*Press Ctrl + F and type "post_max_size" (click Find...", where needed)
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl + F and type "upload_max_filesize" (click Find...", where needed)
*Change the value to the number of Mb you want your site to accept as uploads
*Press Ctrl + F and type "max_execution_time" (click Find...", where needed)
*Change the value to 600
*Press Ctrl and S or the save button.
*Exit your editor.
*Restart your webserver to reload PHP with the edited changes.
**'''For IIS'''
**Open the Start Menu on your server and select "Run"
**Type "iisreset /RESTART"
**For '''Apache 2 and Windows XP'''
**Go to Start > All Programs > Apache > Restart
**'''For Apache 2 and Windows Server'''
**The following command will work as long as you have installed Apache 2 as a service on your Windows Server
**Open your Start Menu on your server and select "Run"
**Type "httpd -k restart"

Your new file size limit should now appear in Administration > Security > Site Policies > Maximum uploaded file size

'''NOTE:''' These instructions also cover the Xampp Windows installer. Just replace C:\PHP with C:\Moodle\server\php and to restart your Moodle with a normal stop-start.

==Modifying the apache config file==
====Ubuntu Linux Instructions====
You may also need to edit the config.php file in the moodle directory:
*Type "gksudo nautilus" to get root permissions
*Navigate to /etc/moodle
*Open apache.conf
*Go to the "<IfModule mod_php5.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Go to the "<IfModule mod_php4.c>" section
*Change "php_value upload_max_filesize = 2M" to a higher value
*Change "php_value post_max_size = 2M" to a higher value
*Save file
*Type sudo /etc/init.d/apache2 restart

===Modifying the .htaccess file===

The following instructions will only work on an Apache web server, and also the Apache server must have Overrides allowed. Traditionally, you could only use .htaccess files when PHP was run as a module of Apache, but with Apache 2.2, this appears to no longer be the case. You can now use the .htaccess file in either module or cgi forms. As well, allowing the use of .htaccess files will cause a performance hit on the server, not a desirable outcome either - so check with your Host.

The .htaccess file is a distributed configuration file, that is, it can be used on a per-folder basis to configure each user's folder and sub-folders. You cannot alter the "AllowOverrides" directive in the Apache configuration file with a .htaccess file, only the Host can set that manually. Usually the Host will place a .htaccess file into your site Root if they do allow you to override the server settings. You can edit it the same as below, and the overrides you set will work. Alternatively, you may create your own .htaccess file in your text editor. It may also be called something else, like .config. If you have any file that starts with a ., you might want to open it in your text editor, just out of curiosity.

Create a file called .htaccess in Moodle's main directory (where 'index.php' is located, not the 'moodledata' directory) that contains the following information:

php_value upload_max_filesize 20971520
php_value post_max_size 20971520
php_value max_execution_time 600

20971520 is the integer value for 20Mb. You can use the following site to [http://www.onlineconversion.com/computer_base2.htm convert MegaBytes to Bytes].

For a more complete description of how to edit the .htacess file, look at this page, [http://httpd.apache.org/docs/current/howto/htaccess.html Apache Tutorial: .htaccess files]

===Modifying the IIS 7.0/7.5 configuration (Windows Server 2008, Windows Server 2008 R2)===
First increase activity and request time outs (allows large files to succeed on slow connections)
FastCGI Settings > Edit (Right-click on PHP application)
Set Process Model > Activity Timeout to '3600' (one hour)
Set Process Model > Request Timeout to '3600' (one hour)
Next set 'Maximum allowed content length'
Request Filtering > Edit Feature Settings:
Set 'Maximum allowed content length' to your desired file size (in bytes) e.g. '536870912' for 512MB (default is approximately 28.6MB)

==Hosted Server==
Things can be a little different with a hosted server for uploaded and downloaded file size. You are probably going to to be told to create or change a .htaccess file, or to modify a php.ini file.

{| class="wikitable"
|[[Image:lightbulb.png]]
|It might be a good idea to talk to with your service provider before you attempt anything. They probably have instructions on "how to" and may have their own limits for uploaded file size. Some hosts measure the file size in gigabytes and others in megabytes. If you are unhappy with their limits, then check your contract and consider changing your provider to one that has a limit and price that you like.
|}

===.htaccess with hosted server===
The one purpose of an .htaccess file is to override the the current limitations of both the server and the php.ini file. Your hosted server should inform you where that file needs be placed in your Moodle, but generally in the root is sufficient. They may already have a standard file you can use, if so, use it - but perhaps not.

To the .htaccess file add the lines:
php_value upload_max_filesize 128M
php_value post_max_size 128M

This will limit uploads to 128MB, but you can make it any size you agree with your provider. The wording may vary slightly, according to the demands of the server.

===php.ini with hosted server===
Some servers will not allow you to change the moodle root .htaccess file and tell you to use a php.ini file for php directives. Here you can use the instruction located in the section above called [[File_upload_size#Modifying_the_php.ini_file|Modifying the php.ini file]].

Find the php.ini file in your moodle subfolder on your hosted server. You might want to copy the file as a backup just in case. Edit php.ini, find "upload_max_filesize" and post_max_size in the code. After the = change the number. Here the max filesize is 20 megabytes.

upload_max_filesize = 20M
post_max_size = 20M

{| class="wikitable"
|[[Image:lightbulb.png]]
|Still not changed? Some hosts using cpanel have a php config program under services/software. Use the "Single php.ini" option and make sure you note the location of the php.ini file to modify. This changes the .htaccess file in the same area and thus the server limit for all programs using php.
|}

{| class="wikitable"
|[[Image:lightbulb.png]]
|Still not changed? [http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size NGINX] system administrators should also add client_max_body_size XXXm; to the "http" section of their nginx main configuration file. ([https://rtcamp.com/tutorials/php/increase-file-upload-size-limit/#change-in-nginx-config see more info]) if you have SSL, that will require you to set the above for the SSL ''server'' and ''location'' too.
|}

==See Also==
*[[Administration_FAQ#How_do_the_limits_on_uploaded_files_work.3F|Administration FAQ Doc page]]
*[[Site_policies#Maximum_uploaded_file_size|Site Policies Doc page]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=39625 Detailed instructions to increase the maximum allowed size for uploaded files] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=97907 Instructions to increase maximum allowed size on hosted servers] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=124441 Help on changing the maximum upload size when installing Moodle via apt-get] forum discussion

[[es:Tamaño de archivo subido]]

[[Category:FAQ|File]]

admin/setting/blocksettingmoodletxt

2021-07-14T13:24:18Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

== MoodleTxt Settings ==

This page contains all the common configuration options for MoodleTxt. At the top of the page you will see two links:

; ConnectTxt Accounts : This link will take you to the ConnectTxt account admin pages, which will allow you to add, update and restrict these accounts. If you have just installed MoodleTxt, this should be your first stop.
; Inbound Message Filters : This link will take you to the inbound filter management page, which will allow you to create filters for inbound SMS messages, routing them to particular Moodle users.

=== Send/Receive Settings ===

The first 4 settings in this section relate to how MoodleTxt gets both message status updates and new inbound messages from the ConnectTxt system. By default, MoodleTxt pulls these updates on a per-request basis, whenever users visit certain pages. However, it can be configured to get these updates automatically, which improves the performance of the block and results in far fewer outbound connections. The available automatic update methods are [[Moodletxt_cron | cron]] and [[Moodletxt_push | push]]. We '''highly''' recommend taking the time to set up push functionality, as it is the fastest and most efficient method of obtaining updates.

{| class="wikitable"
|-
! Field Name
! Field Label
! Description
|-
| Get_Status_On_View
| Automatically get status updates on "View Message" page
| If this box is checked, then whenever a user views the current status of a sent message, the block will first connect to the ConnectTxt system in order to fetch updates. You should uncheck this if you have configured an automatic update option as mentioned above.
|-
| Get_Inbound_On_View
| Automatically get inbound messages on Inbox page
| If this box is checked, then whenever a user views their inbox, the block will first connect to the ConnectTxt system in order to fetch new messages. You should uncheck this if you have configured an automatic update option as mentioned above.
|-
| Push_Username
| XML Push Username
| If you have set up XML push updates (highly recommended) then this is the username you provided to ConnectTxt as part of that setup. ConnectTxt uses this username to authenticate itself with your MoodleTxt installation when connecting to it.
|-
| Push_Password
| XML Push Password
| If you have set up XML push updates (highly recommended) then this is the password you provided to ConnectTxt as part of that setup. ConnectTxt uses this password to authenticate itself with your MoodleTxt installation when connecting to it.
|}

The last two settings in this category control other parameters related to message sending via ConnectTxt.

{| class="wikitable"
|-
! Field Name
! Field Label
! Description
|-
| Protocol_Warnings_On
| Display SSL security warnings
| If you do not have SSL connections to the ConnectTxt server enabled, MoodleTxt will generally display warnings that your data is being transmitted in an unsecure manner. To disable these warnings, uncheck this box.
|-
| Event_Messaging_Account
| Event Messaging Account
| This is the ConnectTxt account that MoodleTxt will use when it is asked to send automatic messages out in response to system events. By extension, this is the ConnectTxt account that will be used to send any messages originating via the MoodleTxt Plus message processor plugin. If no account is selected, then MoodleTxt will be unable to send event-generated messages.
|}

=== Recipient Settings ===

The settings in this section relate to how MoodleTxt captures user phone/name information from the Moodle system, and how it processes that information in order to send SMS messages out. (Future versions of the block will feature improvements in international phone number handling.)

{| class="wikitable"
|-
! Field Name
! Field Label
! Description
|-
| National_Prefix
| National Prefix
| This is the default dialling prefix for phone numbers within your country. It is the digit or set of digits that all phone numbers begin with when being dialled within the country. This defaults to 0, the UK domestic dialling prefix. ('''Note:''' If the phone numbers you enter into MoodleTxt are already formatted internationally, e.g. +441234567890, then this setting is ignored.)
|-
| Default_International_Prefix
| Default International Prefix
| This is the international dialling prefix for phone numbers within your country. This usually consists of a plus '+' sign, along with two or three digits, and is used when dialling into your country from another location. This defaults to +44, the UK international dialling prefix. ('''Note:''' If the phone numbers you enter into MoodleTxt are already formatted internationally, e.g. +441234567890, then this setting is ignored.)
|-
| Phone_Number_Source
| Take phone numbers from
| This option allows you to choose the field in your user database table that MoodleTxt will search for mobile phone numbers (phone1 or phone2). This is largely redundant in modern Moodle setups, where phone2 has been standardised as the mobile phone field, and exists for long-running installations where things may be different. If mobile phone numbers are populated to the phone1 field in your system, then select it from this drop-down.
|-
| Default_Recipient_Name
| Default Recipient Name
| When Moodle cannot find a recipient's name in the database, or cannot match an incoming phone number to any known contact, this is the name/identifier it will record against that message.
|}

=== Proxy Settings ===

If connections between your MoodleTxt installation and ConnectTxt need to be routed via a proxy server, then you can enter the details of that proxy server in this section. '''Please note:''' MoodleTxt currently only supports proxy servers that use either BASIC authentication, or no authentication at all. Newer versions of Moodle have their own proxy settings within the system, and future versions of the block will migrate to use those settings for proxy support.

{| class="wikitable"
|-
! Field Name
! Field Label
! Description
|-
| Proxy_Host
| Proxy Address
| The host/IP address of your proxy server.
|-
| Proxy_Port
| Proxy Port
| The TCP/IP port your proxy server listens on for connections.
|-
| Proxy_Username
| Proxy Username
| If your proxy server requires a username for authentication, then enter it here (BASIC authentication only).
|-
| Proxy_Password
| Proxy Password
| If your proxy server requires a password for authentication, then enter it here (BASIC authentication only).
|}

=== Miscellaneous Settings ===

This section contains any other global settings for MoodleTxt that do not fall into one of the earlier categories.

{| class="wikitable"
|-
! Field Name
! Field Label
! Description
|-
| jQuery_Include_Enabled
| Include main jQuery package
| MoodleTxt uses the popular jQuery library within its user interface. Some Moodle installations already include this library within their active themes. If this is the case, then attempting to load both libraries can cause problems with the system. To turn off MoodleTxt's jQuery installation and have it use the one provided with your theme, uncheck this box. ('''Note:''' You will require at least jQuery 1.6 for this to work.)
|-
| jQuery_UI_Include_Enabled
| Include jQuery UI Library
| MoodleTxt uses the jQuery User Interface library for many common widgets/user interface components. Some Moodle installations already include this library within their active themes. If this is the case, then attempting to load both libraries can cause problems with the system. To turn off MoodleTxt's jQuery UI installation and have it use the one provided with your theme, uncheck this box. ('''Note:''' You will require at least jQuery UI 1.7 for this to work.)
|-
| Show_Inbound_Numbers
| Show source names/numbers in inbox (Default)
| In a classroom situation, such as a survey, where many people can see the messages that are coming into the system, you may wish to anonymise them by hiding the source of the messages. In current versions of MoodleTxt, inbound messages are anonymised by default. To show those message sources on inbox pages by default, then check this box. Since MoodleTxt 3.0, users can override these settings for their own inboxes, so this setting is now a default.
|-
| RSS_Update_Interval
| RSS Update Interval
| This setting controls how often MoodleTxt should check with the RSS feed on the ConnectTxt servers for new updates. (This is being retired, as Moodle 2.3 and up can find updates automatically.)
|-
| RSS_Expiry_Length
| RSS items expire after
| This setting controls how long an update notification from ConnectTxt should be displayed on the MoodleTxt admin panel. (This is being retired, as Moodle 2.3 and up can find updates automatically.)
|}

[[Category:MoodleTxt|Settings]]

Microsoft 365

2021-07-14T13:24:18Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Infobox plugin
|type = set
|set=https://moodle.org/plugins/browse.php?list=set&id=72
|entry =
https://moodle.org/plugins/local_office365 https://moodle.org/plugins/local_o365 https://moodle.org/plugins/auth_oidc https://moodle.org/plugins/repository_office365 https://moodle.org/plugins/block_microsoft https://moodle.org/plugins/theme_boost_o365teams https://moodle.org/plugins/assignsubmission_onenote https://moodle.org/plugins/assignfeedback_onenote
|tracker = https://github.com/Microsoft/o365-moodle/issues
|discussion = https://moodle.org/mod/forum/view.php?id=8273
|maintainer = See plugins directory entries
|float = right
}}
{{Note|[[OAuth 2 authentication]] (enabling users to log in to Moodle with their Microsoft account) and the [[OneDrive repository]] are included in the standard Moodle, so require no additional plugins to be installed.}}
= Introduction =
Microsoft 365 services complement the Moodle learning platform to provide a more productive experience for teachers and students.
== Differences from Moodle Core ==
Although Moodle core now provides Microsoft 365 authentication and basic OneDrive repository support, the Microsoft 365 plugin suite provides a much wider set of features.

A few key features only found in the Microsoft 365 plugin suite:
* User sync from Microsoft 365/Azure AD to Moodle
* Automatic and manual user matching from Microsoft 365/Azure AD to Moodle
* Calendar sync
* Course to Microsoft 365 group sync and shared file repositories
* OneNote assignment submission and feedback types
* Office document embedding using Office web apps
* Fully customizable sign-in experience
= Requirements =
To use the Microsoft 365 plugins, you need the following:
* A Microsoft 365 subscription.
* A Microsoft Azure subscription.
* Moodle version 3.5 or above. The plugins are available for Moodle versions 2.7 and above. Features available in each version, and the support status vary.

= Plugins & Features =
The Microsoft 365 set of plugins contains 5 core plugins, and 4 optional plugins, which provide a wide variety of features to enhance your Moodle instance.

* '''Microsoft 365 Local Plugin''' (local_office365)
** This is a shell plugin which has dependencies on the current version of each of the 4 other core plugins that make up the complete set. Installing this plugin ensures you have the current version of each of the functional plugins installed.
* '''OpenID Connect Authentication Plugin''' (auth_oidc)
** This plugin allows users to log in to Moodle using their Microsoft 365 accounts.
** Users with existing Moodle accounts can switch to using this authentication plugin, and new users can log in with this plugin and have an account created for them.
** If the administrator allows, users can also choose to disconnect from OpenID Connect and revert their previous login method, or to a username/password.
** Features
*** Standards-Compliant OpenID Connect Authentication
*** Supports authorization code or resource-owner credentials grants
**** Users can log in to Moodle by clicking the identity provider on the login page, or by entering their OpenID Connect credentials.
*** Customizable Icon + Identity Provider name
**** The icon and identity provider name shown on the Moodle login page can be customized. A number of prechosen icons are available, as well as the ability to upload your own.
*** Provides hooks to link OpenID Connect accounts to Moodle accounts
**** If you do not want to change your users' login method, you can still connect to an OpenID Connect provider. The plugin provides code-level hooks to link a Moodle account to an OpenID Connect account without changing the Moodle user's authentication method. This means you can obtain tokens from an OpenID Connect service in the background.
*** Optional user-self-service connection and disconnection
**** A user-facing page is available for users to switch to and from OpenID Connect authentication. Access to this page and feature is controlled by a capability so administrators can disable it.
* '''Microsoft 365 support plugin''' (local_o365)
** This plugin provides most of the Microsoft 365 integration back-end. It provides shared code to communicate with Microsoft 365, and powers the calendar sync.
** Features
*** Calendar sync from/to Outlook.
**** Users can sync site events, course events, assignment due dates, and their personal Moodle calendar to their Outlook calendar.
*** User Sync and Matching
**** Users can be synced from Azure AD, or matched with existing users.
*** Teams
**** Teams can be automatically created for each course in Moodle (or you can select which courses are used), and Team membership is kept up-to-date with Moodle enrolments.
*** SharePoint sites for each Moodle course (Deprecated)
**** You can connect your Moodle instance to a SharePoint subsite. Sites below this will be created for each course in your Moodle instance, and the document library from each course subsite is accessible through the OneDrive for Business repository. The course subsite document library is accessible by course teachers, serving as a place for teachers to share documents.
**** This feature is now deprecated. It is mainly used to provide shared document repositories for courses, which can now be accomplished by Teams.
* '''Microsoft Block''' (block_microsoft)
** This block provides a user-facing menu to access various Microsoft 365 integration features, resources, and preferences.
** Links to: Azure AD login preferences, Calendar sync preferences, OneNote notebooks, Teams, and the Microsoft 365 integration user control panel.
* '''OneDrive for Business Repository''' (repository_office365)
** This is a repository plugin that communicates with OneDrive for Business. If the SharePoint link is configured, this also provides access to Moodle course SharePoint sites' document libraries.
** Features
*** Import files into Moodle from OneDrive for Business
*** Upload files into OneDrive for Business from within Moodle
*** Link to files in OneDrive for Business so users always get the most up-to-date version.
*** Embed documents into Moodle courses so users can view documents directly on the site.

== Optional Plugins ==
These 4 plugins provide support for OneNote assignment submission and feedback. While they are not required, they provide a powerful way to submit and review assignments.

* '''Microsoft 365 Teams Theme''' (theme_boost_o365teams)
** This provides a theme to be used when when opening the course page in Teams tab, and provides a seamless user experience for users in Teams.
* '''OneNote support plugin''' (local_onenote)
** This provides supporting and shared code used by all other OneNote plugins. Does not have a user interface or configuration by itself.
* '''OneNote Assignment Feedback''' (assignfeedback_onenote)
** Allows teachers to leave feedback for students using OneNote.
* '''OneNote Assignment Submission''' (assignsubmission_onenote)
** Allows students to submit assignments using OneNote.

== 3rd Party Plugins ==
* '''oEmbed Filter''' (filter_oembed)
** This filter converts links to a variety of sites into oembed-powered interactions.
** Provides [https://mix.office.com/ Office Mix] support for Moodle, allowing you to embed Office Mixes directly into any text within Moodle.

= Resources =

Tooling and guidance on deploying Scalable Moodle Clusters on Azure
* https://github.com/azure/moodle

= Setup =

== Installation ==
The packages are available from:

* The [https://moodle.org/plugins/ Moodle Plugins directory]
** [https://moodle.org/plugins/browse.php?list=set&id=72 Microsoft 365 Plugin Set]
* GitHub
** http://github.com/microsoft/o365-moodle

When you log back in to your Moodle instance, you are presented with the all the plugin configuration options. Save the settings without configuring them for now, you will come back to them later.

For information on installing plugins in Moodle see [[Installing plugins]]

== Configuration ==
After you have the code installed in your Moodle instance, you'll need to do a bit of setup before you can use the plugins.

=== Enable the OpenID Connect Authentication Plugin ===
# Navigate to '''Site Administration > Plugins > Authentication''' and click '''Manage authentication'''
# Locate the OpenID Connect authentication plugin and click the eye icon to enable
# Click the Settings link for the plugin.
# Verify the Authorization and Token endpoints. These should be set by default but if not, set the endpoints to the following:
## '''Authorization Endpoint:''' https://login.microsoftonline.com/common/oauth2/authorize
## '''Token Endpoint:''' https://login.microsoftonline.com/common/oauth2/token
# Note the Redirect URI. This should be the URI of your Moodle instance followed by /auth/oidc/. You will need to enter this value into Azure AD later, so note this value and put it aside.
## For example, https://www.example.com/auth/oidc/
## Notes:
### This is a fixed value that is derived from your Moodle site's configured URL (wwwroot). You cannot change this value directly. If you need to change it for any of the following reasons, you must change your Moodle site's configured domain name ($CFG->wwwroot).
### This URL must be a fully qualified domain name pointing to your Moodle instance.
### If your Moodle installation is configured with an IP address pointing to your instance, you must change $CFG->wwwroot in your config.php to a fully-qualified domain name.
### This domain name does not need to be publicly accessible (i.e. internet-wide), but does need to be accessible to users of your Moodle instance. So, for example, you can use a intranet-only domain name.

=== Prepare your Microsoft 365 account for single sign-on with your Moodle installation ===
You will need an Azure subscription. If you do not have one, you can create one by visiting [http://azure.microsoft.com/en-us/pricing/free-trial/ Microsoft Azure Sign Up].

To use Moodle with Microsoft 365 for SSO, you must configure Microsoft Azure to manage your Microsoft 365 Microsoft Azure Active Directory. A guide is available at [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant this link].

'''Note''': During the setup, you are required to enter a credit card and phone number. If you do not setup virtual machines or use paid services on the subscription, and only use it to access the Azure Active Directory, you will not be charged for the subscription.

=== Register Application in Azure ===
The easiest way to register application in Azure is to run the PowerShell script downloaded from the plugin configuration page. Go to '''Site Administration > Plugins > Local plugins > Microsoft 365 Integration''', it's the '''Download PowerShell Script''' button in the '''Setup''' tab.

You should only follow the manual process if you are unable to setup the AzureAd app via PowerShell script, or you need to verify some specific settings.

==== Manual steps ====
The following steps are involved in the manual setup:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click '''New registration''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle).
# Choose option applicable to your organisation in '''Supported account types''' section. Note that if you choose option other than the "single tenant" one for "Who can use this application or access this API?", you will not be able to use SSO in Teams integration.
# In '''Redirect URI (optional)''' section, select '''Web''' and put the redirect URI from the OpenID Connect authentication plugin configuration. '''Ensure there is a trailing slash for this URI - i.e. https://example.com/auth/oidc/'''
# Click '''Register'''.
# You now have an application registered in Azure for Moodle. Move on to the next section to properly configure it.

===== Configure application =====
# Locate the App.
## Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
## Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
## Click on the App you created for Moodle. Note you may need to change the dropdown from "My apps" to "All apps" if the App was not created by you.
## Locate the '''Application ID''', note this value (write it down or copy it somewhere), and set it aside. You'll need it later.
## Click on the display name of the App to open its settings.
# Enable implicit grant flow.
## From the menu on the left, go to '''Authentication''' link in the '''Manage''' section.
## In the '''Implicit grant''' section, check both "Access tokens" and "ID tokens".
## Save the changes.
# Create client secrets.
## From the menu on the left, go to '''Certificates & secrets''' link in the '''Manage''' section.
## Create a new client secret by clicking '''New client secret''' button.
## Enter a description, and select a duration for "Expires"
## Click '''Add'''
## A value will appear under '''Value''', note this key value (write it down or copy it somewhere) and set it aside. You'll need it later.
# Expose an API - only required if Teams sync feature is used.
## From the menu on the left, go to '''Expose an API''' link in the '''Manage''' section.
## Click the "Set" link next to "Application ID URI".
## This should open a "Set the APP ID URI" prompt, with a default value such as "api://00000000-0000-0000-0000-000000000000", where the GUID is the same as your Application ID.
## Replace this value with "api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000", where URL.TO.MOODLE is the wwwroot of your Moodle site, and the GUID is the same was default value, i.e. your Application ID.
## Click "Save" to create the Application ID URI.
## Click "Add a scope".
## Enter "access_as_user" as scope name.
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to "Teams can access the user’s profile".
## Set "Admin consent description" to "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to "Enable Teams to call this app’s APIs with the same rights as the user"
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
## In the "Authorized client applications" section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
### 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
### 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Configure App Permissions.
## Click the '''API permissions''' link in the '''Manage''' section.
## Click '''Add a permission''' button.
## In '''Select an API''' section, choose '''Microsoft APIs''' tab, then choose "Microsoft Graph".
## Click the checkbox for the following permissions in each of the "Application" and "Delegated" permissions sections according to the table below.
## After all the permissions are added, click the "Grant admin consent for YOUR ORGANISATION NAME" link.
{| class="wikitable"
|-
! Type
! Permission
! Display Name
! Use
|-
| rowspan="9" | Application Permissions
| '''Domain.ReadWrite.All'''
| '''Read and write domains'''
| Required to automatically detect your Microsoft 365 tenant during setup.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.Read.All'''
| '''Read directory data'''
| Required for setup detection and verification.
|-
| '''Calendars.ReadWrite'''
| '''Read and write calendars in all mailboxes'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite.All'''
| '''Read and write files in all site collections'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
|-
| '''MailboxSettings.Read'''
| '''Read all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write all user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| rowspan="16" | Delegated Permissions
| '''Notes.ReadWrite.All'''
| '''Read and write all OneNote notebooks that user can access'''
| Required for the OneNote integration to create notebooks, sections, and pages for assignments.
|-
| '''User.Read'''
| '''Sign-in and read user profile'''
| Required to sign users in using Microsoft 365, and to access Microsoft 365 APIs.
|-
| '''User.ReadWrite.All'''
| '''Read and write all users' full profiles'''
| Required to sync user information between Moodle and Microsoft 365.
|-
| '''Group.ReadWrite.All'''
| '''Read and write all groups'''
| Required for course group integration.
|-
| '''Directory.ReadWrite.All'''
| '''Read and write directory data'''
| Required for setup detection and verification.
|-
| '''Directory.AccessAsUser.All'''
| '''Access directory as the signed in user'''
| Required to access Microsoft 365 APIs.
|-
| '''Calendars.ReadWrite'''
| '''Have full access to user calendars'''
| Required for calendar event sync.
|-
| '''Files.ReadWrite'''
| '''Have full access to user files'''
| Required for the Microsoft 365 repository to access, download, and upload files to OneDrive.
|-
| '''Sites.Read.All'''
| '''Read items in all site collections'''
| Required for SharePoint integration (deprecated)
|-
| '''MailboxSettings.Read'''
| '''Read user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''MailboxSettings.ReadWrite'''
| '''Read and write user mailbox settings'''
| Required for syncing Outlook default timezone settings of the user.
|-
| '''openid'''
| '''Sign users in'''
| Required to sign users in using Microsoft 365 (required for all integration).
|-
| '''offline_access'''
| '''Maintain access to data you have given it access to'''
| Required for Teams SSO.
|-
| '''email'''
| '''View users' email address'''
| Required for Teams SSO.
|-
| '''profile'''
| '''View users' basic profile'''
| Required for Teams SSO.
|}
When you're done, click '''Add permissions''' at bottom of the page.

=== Enter Azure application credentials into Moodle ===
# Navigate to the OpenID Connect authentication plugin's settings page (Site Administration > Plugins > Authentication > OpenID Connect)
# Enter the '''Application ID''' value you noted earlier from Azure into the '''Application ID''' box on the screen.
# Enter the '''Key''' value you noted earlier from Azure into the "Key" box on the screen.
# Click "Save changes" at the bottom of the screen.

=== Configure the Microsoft 365 support plugin ===
# Navigate to '''Site Administration > Plugins > Local plugins''' and click '''Microsoft 365 Integration'''
# Complete each of the steps as follows:
# '''Choose connection method'''
## Choose the method you want to use to connect to Microsoft 365. Unless you have a special reason to use the System API user, choose '''Application access'''.
## Click '''Save changes'''
# '''Admin consent & additional information'''
## '''Admin consent:''' Every time you change a '''Requires admin''' permission in Azure, you will need an administrator to provide consent to use the permission. Clicking the '''Provide admin consent''' button will take you to a log in screen on Microsoft 365. An administrator will have to log in, and then will be given the option to approve the new permissions.
## '''Azure AD Tenant:''' This is the domain name that identifies your Microsoft 365 subscription, for example "contoso.onmicrosoft.com". If you know it, enter it in this box, if not, click the "Detect" button to attempt to detect the correct value.
## '''OneDrive for Business URL:''' This is the URL that your users use to access OneDrive for Business. This can usually be determined from your AzureAD tenant, for example, if your tenant is "contoso.onmicrosoft.com", your OneDrive for Business URL is "contoso-my.sharepoint.com." If you know the URL, enter it here, otherwise click "Detect" to attempt to detect the correct value. Only enter the domain name, do not include "http://", "www." or any trailing slashes. For example "contoso-my.sharepoint.com", not "https://contoso-my.sharepoint.com/"
## Click Save changes.
# '''Verify Setup'''
## This tool verifies that Azure has been correctly set up. Click the "Update" button to check setup.
## If the tool reports any missing permissions, return to Azure and ensure that all required permissions have been added to your configured application for Moodle.

== Connecting users to Microsoft 365 ==
To use any Microsoft 365 features, a Moodle user must be connected to a Microsoft 365 user that has an active Microsoft 365 subscription. There are two ways to connect a Moodle user to a Microsoft 365 user.

=== Switch the user to use OpenID Connect authentication. ===
With this method, the user will log in to Moodle using their Microsoft 365 account credentials.
* Users who do not yet have a Moodle account can simply follow the normal OpenID Connect login process (see: [[Office365#Basic_Usage]]). If a Moodle account is not found for a user logging in with OpenID Connect, an account will be created for them.
* To migrate an existing Moodle user to OpenID Connect authentication, see [[Office365#Switching_existing_Moodle_users_to_use_Office_365_to_log_in]].

=== Link a Moodle user to a Microsoft 365 user. ===
Users in Moodle can also be linked to Microsoft 365 users without changing the Moodle user's authentication method. Users will be able to log in as they always have, and still use all the Microsoft 365 features.
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# As the user to link to Microsoft 365, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# There will be a "Connection Status" indicator box on the right side of the screen, click the "Click here to connect" link.
# You will be brought to the AzureAD authentication screen. Log in with the Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# This user is now connected to the Microsoft 365 user.

= Microsoft 365 Integration Local Plugin =
== Sync Settings ==
These features are accessible from the plugin's settings page (Site Administration > Plugins > Local plugins > Microsoft 365 Integration), on the '''Sync Settings''' tab.

=== User Sync ===
This option controls how users are synced from Azure AD to Moodle. If enabled, users from Azure AD can be automatically created in Moodle. This feature can also delete users in Moodle when they are deleted from Azure AD, or attempt to automatically match Moodle users with users in the connected Azure AD.

The main benefit of using this option, compared to having accounts created as users log in using OpenID Connect, is that you can manage and enrol users before they first log in, so everything is ready to go the first time they access Moodle.

'''Notes:'''
* The sync job runs in the Moodle cron, and syncs 1000 users at a time.
* By default, this runs once per day at 1:00 AM in the time zone local to your server.
* To sync large sets of users more quickly, you can increase the freqency of the Sync users with Azure AD task using the Scheduled tasks management page. See [[Scheduled_tasks]].

There are several options that affect user sync:
* '''Create accounts in Moodle for users in Azure AD''': This will create users in Moodle from each user in the linked Azure Active Directory. Only users which do not currently have Moodle accounts will have accounts created. New accounts will be set up to use their Microsoft 365 credentials to log in to Moodle (using the OpenID Connect authentication plugin), and will be able to use all the features of the Microsoft 365 plugin set.
* '''Update all accounts in Moodle for users in Azure AD''': This will update all users in Moodle from each user in the linked Azure AD.
* '''Delete previously synced accounts in Moodle when they are deleted from Azure AD''': This will delete users from Moodle if they are marked as deleted in Azure AD. The Moodle account will be deleted and all associated user information will be removed from Moodle. Be careful!
* '''Match preexisting Moodle users with same-named accounts in Azure AD''': This will look at the each user in the linked Azure Active Directory and try to match them with a user in Moodle. This looks for matching usernames in Azure AD and Moodle. Matches are insensitive and ignore the Microsoft 365 tenant. For example, "BoB.SmiTh" in Moodle would match "bob.smith@example.onmicrosoft.com". Users who are matched will have their Moodle and Office accounts connected and will be able to use all Microsoft 365/Moodle integration features. The user's authentication method will not change unless the setting below is enabled.
* '''Switch matched users to Microsoft 365 (OpenID Connect) authentication''': This requires the "Match" setting above to be enabled. When a user is matched, enabling this setting will switch their authentication method to OpenID Connect. They will then log in to Moodle with their Microsoft 365 credentials. Note: Please ensure the OpenID Connect authentication plugin is enabled if you want to use this setting.
* '''Assign users to application during sync''': The sync will search all users in the linked Azure AD (other than those excluded by the User Creation Restriction, however not all users may be assigned to the Moodle application you created in Azure AD App Registration during early setup. This setting will assign any Azure AD users with a matching Moodle account to the Azure AD App for Moodle you created.
* '''Sync Microsoft 365 profile photos to Moodle in cron job''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - by cron job.
* '''Sync Microsoft 365 profile photos to Moodle on login''': User's photos in the Moodle profile will be updated with their image from their Azure AD profile - on login.
* '''Perform a full sync each run''': By default user sync will only sync changes from Azure AD. Checking this option will force a full user sync each time.
* '''Match Azure usernames to Moodle emails instead of Moodle usernames during the sync''': Enabling this option will match Azure usernames to Moodle emails instead of the default behaviour which is Azure usernames to Moodle usernames.

====User Creation Restriction====
During user sync, by default, all users from Azure AD will be created in Moodle. This setting allows you to set a required field and value that a user must have in Azure to have an account created in Moodle. For example, if you wanted to only have users from the "IT" department syncing into Moodle, you would choose the "Department" field, and enter "IT".
====User Field Mapping====
This controls how information is synced from Azure AD to Moodle. The first column lists Azure fields, the second column lists Moodle fields, and the third column controls when information is synced.
To create mappings:
# Click "Add Mapping"
# In the row that appears, select an Azure field to bring into Moodle.
# In the second column on the same row, select a Moodle field to copy the value into.
# In the third column on the same row, choose whether this only happens on user creation, on user login, or both.
# Click "Save Changes" at the bottom of the page.

To Delete A Mapping
# Click the "X" button at the end of the row you want to delete.
# Click "Save changes" at the bottom of the page.
# Note this will only prevent future information syncing, it will not undo past operations.

=== Teams Sync ===
The Teams sync setting creates teams in Microsoft Teams for courses in Moodle. Teams creation effectively results in team members being added to a Microsoft 365 group, enabling all group features to be usable.

Features:
* Teams (group) membership is kept up-to-date with enrolments in Moodle.
* Provides an easy way to address all users in a course from Microsoft 365. For example, a teacher can share a document from OneDrive with all of their students by choosing the user group, i.e. Teams members, for their course - they don't have to choose each student individually.
* Course group file stores are accessible from the Microsoft 365 Moodle file repository plugin, allowing users to access group files from Moodle.

The Teams sync option allows a great deal of customization. An administrator can choose to create Teams for all courses, and enable all settings, or customize the implementation. If administrators choose the "Customize" option for this setting, administrators can choose which courses have Teams created, and choose which features are enabled for each course.

Once enabled, new Teams will be created every cron run for any enabled course that doesn't have a team set up. Once Teams are set up, membership will be maintained automatically whenever someone joins or leaves a Moodle course.

==== Teams vs Group ====
Microsoft Teams share the same base with Microsoft 365 groups in many ways, notably they share the same GUID, and Team members are also group members, however, there is a significant difference in the requirements for creating a Team and creating a group - Team creation require at least one Team owner, while groups can be created without owner. This unfortunately has an impact on the Teams sync feature, when a Moodle course is processed by the Teams sync feature for the first time, assuming the "Teams" feature is enabled:
* If the course has at least one teacher who can be matched to a Microsoft 365 user enrolled, a Team will be created, with the teacher as Team owner,
* If the course has no user enrolled with teacher role, or none user enrolled with teacher role is Microsoft 365 user, only a group will be created.

== Advanced settings ==
=== Administrator Tools ===
* '''Tenants''': This tool allows you to add additional Microsoft 365 tenants to be used with Moodle. Users from additional tenants can log-in to Moodle using their Microsoft 365 account, and use features like calendar sync and the OneDrive repository.
* '''Health check''': If you are experiencing problems with any Microsoft 365 / Moodle features, click the '''Health Check''' link to run tests on your system and look for potential problems.
* '''Connections''': This tool allows administrators to see and manage the connections between their Moodle users and Microsoft 365 accounts. Each user in the system is listed alongside the Microsoft 365 username the user is connected to, if any. Administrators can choose to manually connect or disconnect each user.
* '''User Matching''': This tool allows administrators to manually match Moodle and Microsoft 365 users using a CSV file. Administrators can upload a CSV file containing, on each line, a Moodle username, and Microsoft 365 username, and a 1 or 0 indicating whether to enable Microsoft 365 login for that user. Once uploaded, the file is processed in batches during the Moodle cron. The tool page will display the progress of this process.
* '''Maintenance Tools''': These tools perform maintenance tasks that can help solve problems which may crop up from time to time. Generally, users should not need these tools unless they encounter the specific situation these tools are designed to solve.
** '''Resync users in groups for courses''': Course group membership is kept up-to-date as users are enrolled and un-enrolled from courses in Moodle. If this membership gets out-of-date for whatever reason, this tool will force a resync of group membership.
** '''Recreate deleted Microsoft 365 groups''': Course groups are created from Moodle courses when using the course group feature. If a group is manually deleted from the Microsoft 365 administrator panel, this tool will recreate it.
** '''Generate debug data package''': This tool will generate a package of information that can be sent to the plugin suite maintainers to help debug problems in environment and setup. While no API keys are present, this information does contain a lot about your environment and setup, so please be careful about who you send this information to.
** '''Cleanup OpenID Connect Tokens''': If your users are experiencing problems logging in using their Microsoft 365 account, trying cleaning up OpenID Connect tokens. This removes stray and incomplete tokens that can cause errors. WARNING: This may interrupt logins in-process, so it's best to do this during downtime.
** '''Cleanup User Sync Delta Tokens''': If user synchronisation is not fully working after updating it user sync settings, it may be caused by an old delta sync token. Cleaning up the token will remove force a complete re-sync the next time when the user sync is run.

===Other advanced settings===
* '''Single sign off''': If enabled, when a Moodle user using OIDC authentication method signs off from Moodle, Moodle will attempt to log the user off from Microsoft 365 as well.
* '''Microsoft 365 for China''': Microsoft 365 in China differs slightly in some technical aspects. If you are using Microsoft 365 for China, select this box to ensure everything will work properly.
* '''Record debug messages''': If you experience problems using any Microsoft 365 features in Moodle, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administration > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".
* '''Minimum inexact username length to switch to Microsoft 365''': When using automatic user matching, this setting can be used to exclude accounts with short names. The intended use of this is to avoid matching generic accounts like "admin". This setting is the minimum length of a username required for automatic matching to match users.
* '''Profile photo refresh time''': Profile photo syncing can be a resource-intensive process, so this setting allows you to set a minimum time between profile photo refresh runs.
* '''Custom theme (Advanced)''': This allows you to choose the theme to use in when accessing Moodle pages from the Moodle Teams tab.

===Legacy settings===
'''These features are deprecated and is likely to be removed in a future version.'''

===Preview features===
From time-to-time, we add features that use brand-new APIs or are slightly experimental in some way. These features often become part of our regular feature offering once they mature, but if you want to see the latest features we're working on, you can enable this setting to enable all preview features. Be careful though! These features do break from time to time.

==Teams Settings==
This section allows configuration Moodle and Microsoft Teams integration. When fully configured, the integration will
* Automatically create Teams for Moodle courses configured to be synced.
* Automatically sync Moodle course users to Teams.
* Automatically create a Moodle tab in the general channel of the created Team, linking to the Moodle course page.
* Allow users to use Moodle courses right from Teams.
* Allow users to ask questions about their courses, assignments, grades and students from Teams using Moodle assistance bot.
* Forward all Moodle notifications to users to Teams.
Some features can be disabled if needed.

===Prerequisite===
# '''OpenID Connect Authentication''' plugin is enabled and configured.
# '''Allow frame embedding''' is enabled in '''HTTP security''' section of site configuration.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "HTTP security" in "Security" section.
## Find '''Allow frame embedding''' setting and make sure it's enabled.
## Save changes.
# Web services are enabled on the site.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Site administration" tab, go to "Advanced features".
## Find '''Enable web services''' setting and make sure it's enabled.
## Save changes.
# '''Moodle Microsoft 365 Webservices''' are enabled.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Plugins" tab, go to "External services" in "Web services" section.
## From the list of web services in the "External service" part in "Built-in services" section, find '''Moodle Microsoft 365 Webservices'''.
## If the web services is disabled, i.e. greyed out, go to its settings and enable it.
# Give '''Authenticated user''' role permission to create web service token.
## Login to the site as site administrator.
## Go to "Site administration", then in the "Users" tab, go to "Define roles" in "Permissions" section.
## In the "Manage roles" tab, from the list of roles, find "Authenticated user" role, and click the edit icon for the role.
## From the list of permissions, find "Create a web service token", i.e. moodle/webservice:createtoken, and set it to allow.
## Save changes.

=== Register Application in Azure ===
Note this is different from the application registered above to allow user login integration.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from the '''Manage''' section on the left.
# Click '''New application''' on the top menu.
# Enter a name for your application (can be anything you want, but should let you know this is for Moodle Teams integration).
# Choose option applicable to your organisation in '''Supported account types''' section.
# Click '''Register''' button to finish registration.
# You should be redirected to the settings page of the newly registered app; if not, find the app from the list of apps, and go to the settings page by clicking on its name.
# Note the '''Application (client) ID''' of the app, which will be used in plugin configuration in Moodle.
# From the '''Manage''' section on the left of the page, go to '''Certificates & Secrets''', and create a new client secret by clicking the '''New client secret''' button. Note the secret which will be used in plugin configuration in Moodle.
# In '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration in Moodle, fill in the '''Application (client) ID''' and the client secret in '''Application ID''' and '''Client Secret''' settings respectively.
# Save changes.

=== Update authentication application settings in Azure ===
When performing '''Step 1/3: Register Moodle with Azure AD''' in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration, the PowerShell script downloaded from Moodle was used, you can skip this section. If you followed manual steps, or the application registration was completed before, you will need to follow these steps.
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Click the app created for Moodle. Note this is not the app for Moodle Teams integration, but the one used for authentication. You may need to show '''All applications''' if the app wasn't created by your account.
# Go to the settings of the application by clicking its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the following entry, in type '''Web''':
## https://your.moodle.url/local/o365/sso_end.php
# If bot feature is to be enabled, also add the following entry, in type '''Web''':
## https://token.botframework.com/.auth/web/redirect
# Save changes.

=== Bot configuration ===
This section is only required if you want to enable bot features in the configuration. If bot feature is not required, please skip.
==== Bot deployment====
# Go back to '''Teams Settings''' section of '''Microsoft 365 Integration''' configuration in Moodle as site administrator.
# Make sure '''Application ID''' and '''Client secret''' are configured and saved.
# Click '''Deploy to Azure''' button. This will start the process of bot deployment in Azure Portal in a popup window.
# Configure the following in the '''Custom deployment''' window:
## Choose your '''Subscription'''.
## Choose your '''Resource group'''. you may need to create a new one.
## Choose your '''Location'''.
## '''LUIS Pricing Tier''' - [https://azure.microsoft.com/en-us/pricing/details/cognitive-services/language-understanding-intelligent-services/ LUIS pricing tiers] are explained here. The free tier should be able to get you started.
## '''LUIS Region''' - Region where the LUIS resource will be deployed.
## '''Bot Application ID''' - the application ID of the Moodle Teams integration application, which is the same as '''Application ID''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## '''Bot Application Password''' - the client secret of the Moodle Teams integration application, which is the same as '''Client Secret''' in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
## ''Moodle URL'''.
## '''Azure AD Application ID''' - The Application ID saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Application Key''' - The Application Key saved in the '''Setup''' tab of '''Microsoft 365 Integration''' configuration.
## '''Azure AD Tenant''' - The tenant name (xyz.onmicrosoft.com) of your Azure AD tenant.
## '''Shared Moodle Secret''' - Paste the '''Shared Moodle Secret''' setting of in the '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration.
Once all configured, agree the terms and conditions, and click '''Purchase'''. This will start the bot deployment, which can take a few minutes to finish.

==== Post deployment configuration====
After bot deployment is finished:
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# In the '''Navigation''' section of the page, go to '''Resource groups'''.
# From the list of resource groups, select the one in which the bot was created and deployed.
# One of the resources in the group should be in type '''Web App Bot'''. Click its name to go to settings.
# Copy the '''Messaging endpoint''' of the resource (e.g. https://provisioned-bot-name.azurewebsites.net/api/messages), rename messages to webhook (Ex: https://provisioned-bot-name.azurewebsites.net/api/webook)
# Paste this endpoint to the '''Bot webhook end point''' field in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Check '''Bot feature enabled''' box in '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Save changes.

=== Add Moodle app to Teams ===
Once all configured, you are ready to add Moodle app to Teams.
# Go to '''Teams Settings''' tab of '''Microsoft 365 Integration''' configuration page.
# Click '''Download manifest file''' button. This will download a manifest file (in .zip format) which contains the Moodle app.
# Follow [https://docs.microsoft.com/en-gb/microsoftteams/platform/concepts/deploy-and-publish/apps-upload these instructions] to upload the app to the app catalog of your tenant.
# Once the app is uploaded to the catalog of your tenant, it can be used in any Teams in the tenant.

== Teams Moodle app settings==
After downloading the manifest file of Moodle app, a new tab '''Teams Moodle app''' will be made available in '''Microsoft 365 Integration''' configuration page, which contains a single setting to configure the app ID of the Moodle app uploaded to Teams. This is optional but recommended. If configured, all new Teams created by Moodle course sync will:
* automatically install the Moodle app,
* automatically create a Moodle tab in the '''General''' channel.
* automatically configure the Moodle tab to point to the Moodle course that's related to the Team.

To configure the field, follow these steps:
# Log in Teams, and go to app catalog by clicking the '''Apps''' button from the navigation bar on the left.
# Find the '''Moodle''' app uploaded.
# Click the option icon of the app, which is located at the top right corner of the app image.
# Click '''Copy link'''.
# In a text editor, paste the copied content. It should contain an URL such as https://teams.microsoft.com/l/app/00112233-4455-6677-8899-aabbccddeeff.
# The last part of the URL, i.e. 00112233-4455-6677-8899-aabbccddeeff, is the app ID.
# Paste the app ID in the '''Moodle app ID''' setting on '''Teams Moodle app''' tab of '''Microsoft 365 Integration''' configuration page in Moodle.
# Save changes.

= OpenID Connect Authentication Plugin =
== Basic Usage ==
Once configured, you should see a link named "OpenID Connect" on the Moodle login page. Clicking this link will redirect the browser to the identity provider. Users will log in there, and will be redirected back to Moodle. If they have logged in to Moodle using OpenID Connect before, they will be logged in to their existing Moodle account. If they have not logged in to Moodle with OpenID Connect before, an account will be created for them.

Note: If the "Prevent account creation when authenticating" setting is enabled in Moodle, new accounts will not be created.

== Settings ==
There are a number of options you can use to customize how the plugin behaves. To configure the plugin, visit the plugin's settings page. (Site Administration > Plugins > Authentication > OpenID Connect)

====Provider Name====
The name entered here will be used through the OpenID Connect plugin and the Microsoft 365 plugins to refer to the system used to log users in. For example, if your users are used to calling their Azure AD account their "School" account, you enter "School account" here, and all references to authentication will be "Log in with your School account".

====Auto-Append====
When using the "Username/Password" login flow, this setting with automatically append a given string to an entered username. This is useful in Azure AD usernames, where a single domain name is often used for every user - i.e. [user]@contoso.onmicrosoft.com. Users would normally have to enter this entire username to successfully log in to Moodle, but in this example, entering "@contoso.onmicrosoft.com" here means users would only have to enter their unique username, i.e. "bob.smith", instead of "bob.smith@contoso.onmicrosoft.com".

====Domain Hint====
If users have several different Azure AD accounts with different tenants (i.e. @contoso.onmicrosoft.com, @example.onmicrosoft.com), but Moodle only uses one of these tenants, you can enter that tenant in this box to have the Azure AD login screen only ever suggest accounts from that tenant.

====Login Flow====
This setting changes how users log in to Moodle using the plugin. You can redirect users to the OpenID Connect provider's login page, or have users enter their credentials directly into Moodle. See the "Login Flows" section below for further information.

====User Restrictions====
This setting allows you to restrict the users that can log in to Moodle using OpenID Connect (Azure AD).

Once you've entered at least one user restriction, users logging in to Moodle must match at least one entered pattern.

How to use user restrictions:
# Enter a regular expression pattern that matches the usernames of users you want to allow.
# Enter one pattern per line
# If you enter multiple patterns a user will be allowed if they match ANY of the patterns.
# The character "/" should be escaped with "\".
# If you don't enter any restrictions above, all users that can log in to the OpenID Connect provider will be accepted by Moodle.
# Any user that does not match any entered pattern(s) will be prevented from logging in using OpenID Connect.

====Record debug messages====
If you experience problems using OpenID Connect, enable this setting. Once enabled, errors will be recorded to the Moodle log for review. These errors can help you or the plugin developers debug and fix the problem. The error log can be viewed by navigating to Site Administation > Reports > Logs, changing the "All activities" select box to "Site errors", and clicking "Get these logs".

====Custom Icon====
This setting allows you to choose from a selection of predefined icons to appear next to the identity provider link on the login page. You can also upload your own icon.

# Visit the plugin settings page (Site Administration > Plugins > Authentication > OpenID Connect)
# Locate the "Icon" section of the settings page.
# There are several predefined icons to choose from, clicking an icon will use that icon on the login page.
# To use a custom icon, use the file picker below the "Icon" setting.
## This image will not be resized on the login page, so we recommend uploading an image no bigger than 35x35 pixels.
## If you have uploaded a custom icon and want to go back to one of the stock icons, click the custom icon in the file picker and click "Delete", then "OK", then "Save Changes" at the bottom of the settings page. The selected stock icon will now appear on the Moodle login page.

== Login flows ==
This plugin supports two different methods for users to log in: Authorization Request and Username/Password Authentication

=== Authorization Request ===
This flow redirects the user to Microsoft 365 to log in and are then brought back to Moodle logged in.

Using this flow:
# The user clicks the name of the identity provider (What you entered in the "Provider Name" box at the top of the settings page.) on the Moodle login page.
# The user is redirected to Microsoft 365 to log in.
# Once successfully logged in, the user is redirected back to Moodle where the Moodle login takes place transparently.

=== Username/Password Authentication ===
This login flow works like a classic username and password, except the user uses their Microsoft 365 account information.

Using this flow:
# The user enters their Microsoft 365 username and password directly into the Moodle login form.
# Their credentials are securely sent to Microsoft 365 for verification.
# If the credentials are verified, the user is logged in to Moodle.

== Switching existing Moodle users to use Microsoft 365 to log in ==
If a user logs in to Moodle using OpenID Connect but does not have a Moodle account, one will be created for them. However, existing Moodle users can be migrated to use OpenID Connect and provide a connection to Microsoft 365.

# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# Click the '''Microsoft 365 Login'' link under '''Microsoft 365 Features'''
# Click the "Start using Microsoft 365 to log in to Moodle." link.
# You will be redirected to Microsoft 365 to log in. Log in with the account you'd like to link to the Moodle account you're using.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# The Moodle account will now use Microsoft 365 to log in. '''The previous login method will not work.'''
# The Moodle user can now use any of the Microsoft 365 features in Moodle.

== Connecting existing Moodle users to Microsoft 365 without changing login method ==
# Ensure the Microsoft block has been added to a page in Moodle (for example, the Moodle dashboard).
# Log in as the user to be migrated, visit a page that has the Microsoft block visible.
# Click the '''Connect to Microsoft 365''' link in the Microsoft block.
# You will be brought to the '''Microsoft 365 / Moodle Control Panel'''.
# There will be a "Connection Status" indicator box on the right side of the screen, click the "Click here to connect" link.
# You will be brought to the AzureAD authentication screen. Log in with the Microsoft 365 user's credentials you'd like to connect to the Moodle user you are logged in as.
## '''NOTE:''' If you're already logged in to Microsoft 365, you will not have to enter your credentials on the Microsoft 365 login page. This Microsoft 365 account will be linked to the Moodle account. Ensure you are logged in to the correct account, or log out of Microsoft 365 first to show the Microsoft 365 login screen.
# If login was successful, you will be brought back to the '''Microsoft 365 / Moodle Control Panel''' page, where the Microsoft 365 connection indicator should now read '''Active'''.
# The Moodle account is now linked to the Microsoft 365 account and can use Microsoft 365 features as that user.
# The Moodle user's login method will not change, the user will log in to Moodle as they always have.

= OneDrive for Business Repository =
The OneDrive for Business repository allows users using the Microsoft 365 integration plugins to connect to their OneDrive for Business as a Moodle repository.

== Downloading and linking files ==
# When using a filepicker anywhere in Moodle, you'll see a list of repositories on the left side of the popup. Look for and click on "OneDrive for Business".
# You'll see two folders - "My Files" and "Courses". Click the folder for the document library you want to access.
## '''My Files''' contains all documents in your personal OneDrive for Business
## '''Courses''' will list all Moodle course shared document libraries that you have access to. If you want to download files from one of these, you'll click "Courses", then click the folder for the course you want to access.
# You will now see a list of all the files and folders in your OneDrive.
# Click the file you want to download into Moodle.
# Choose to "Make a copy of the file", or "Create an alias/shortcut to the file."
## If you want to download a copy of the file as it is now, choose "Make a cope of the file". This will copy the file into Moodle, and will then use the local Moodle copy when the file is accessed from within Moodle. Any changes to the file in OneDrive will not be seen in Moodle.
## If you want to link a file choose "Create an alias/shortcut to the file". This will create a link in Moodle to the file in OneDrive, and the file will be accessed from OneDrive directly. Any changes to the file in OneDrive will be seen when accessing the file from Moodle.
# You can change other file information like the filename or author name using the respective text fields. This information is only applicable to the Moodle side of the file, and will not transfer to OneDrive.
# Click "Select this file".

== Uploading files ==
You can upload files into both your personal OneDrive for Business document library and a course SharePoint document library from the filepicker interface.

# When accessing a OneDrive document library from a file picker, you will see an "Upload New File" item in the list of files and folders.
# Click the "Upload new file" item.
# Choose the file you want to upload and click "Upload this file".
# The file will be uploaded to OneDrive and selected for the file picker.

== Embedding Office documents ==
This repository allows users to embed Office documents from OneDrive into a course and have the live version viewable using Office web apps.

# Start as a user connected to Microsoft 365 and who has access to modify a course.
# Turn on editing for the course and choose "Add an activity or resource" for the section of the course you want to add the document.
# Choose the "File" resource to add to the course.
# In the "Content" section of the file resource settings page, click the "Add" button in the filepicker
# Choose the "OneDrive for Business" repository and choose your Office document.
# When you select a file, make sure "Create an alias/shortcut to the file" is selected, the click "Select this file"
# Expand the "Appearance" section, and choose "Embed" for the "Display" select box.
# Click "Save and display"
# You should see the file embedded into the page.

= OneNote =
OneNote is now available through Microsoft 365. If you have installed all the plugins (for example, by installing [https://moodle.org/plugins/view/local_office365]) then you already have the OneNote plugins installed. To access OneNote using your Microsoft 365 subscription, add OneNote to the list of applications in your Azure application. This is done the same way you configured Azure permissions, above. Note that OneNote is still in preview, and may not be available to everyone yet. If you don't see OneNote in the list of applications to add to your Azure application, you can try logging in to a desktop OneNote application using an administrator account in your Microsoft 365 tenant. This sometimes expedites to the process of adding the OneNote preview to your tenant.

= Notes on special release =
== 3.8.0.4 and 3.9.1 release==
3.8.0.4 and 3.9.1 release of the plugins on 29 September 2020 introduced improvements on SSO integration for Moodle in Teams as well as Single Sign Off support, but requires additional actions from Moodle and Azure admins.

=== Moodle and Teams SSO integration ===
The new releases is capable of getting a user token from either Teams desktop/mobile app or Teams web app, and attempt to log in as the user in the Moodle Teams tab. In order for it to work, changes in 3 sections are required.

==== Update Azure app settings ====
# Sign in to the [https://portal.azure.com Microsoft Azure Management Portal].
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# Under '''Manage''', select '''Expose an API'''.
# Select the "Set" link to generate the Application ID URI in the form of api://{AppID}. Insert your fully qualified domain name (with a forward slash "/" appended to the end) between the double forward slashes and the GUID. The entire ID should have the form of: api://fully-qualified-domain-name.com/{AppID}. e.g. api://URL.TO.MOODLE/00000000-0000-0000-0000-000000000000.
# If you get errors when selecting the "Set" link, it may be because the '''Supported account types''' setting of your app is set to a value rather than the one with "single tenant". Try updating this value to get it working.
# Select the "Add a scope" button. In the panel that opens:
## enter "access_as_user" as the "Scope name".
## Set "Who can consent?" to "Admins and users".
## Set "Admin consent title" to be "Teams can access the user’s profile".
## Set "Admin consent description" to be "Allows Teams to call the app’s web APIs as the current user".
## Set "User consent title" to be "Teams can access the user profile and make requests on the user's behalf".
## Set "User consent description" to be "Enable Teams to call this app’s APIs with the same rights as the user".
## Ensure that "State" is set to "Enabled".
## Select the "Add scope" button to save.
# In the Authorized client applications section, identify the applications that you want to authorize for your app’s web application. Select Add a client application. Enter each of the following client IDs and select the authorized scope you created in the previous step:
## 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application)
## 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)
# Under '''Manage''' then '''API permissions''', ensure the following permissions are added under "Microsoft Graph" > "Delegated permissions":
## User.Read (enabled by default)
## email
## offline_access
## OpenId
## profile
# Under '''Manage''' then '''Authentication''', ensure the following boxes are checked for "implicit grant":
## ID Token
## Access Token.

==== Download updated manifest file ====
# Login to Moodle as site administrator.
# Go to "Microsoft 365 Integration" page in the site admin section.
# Go to "Teams Settings" tab.
# Verify settings on the page, note that two new settings are added in this release:
## '''Microsoft app ID for the Moodle Teams app''': This is used in the "ID" field of [https://docs.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema Teams app manifest file], which is essentially a self generated app ID to identify itself. It should be set to the default value in most use cases, otherwise it may affect upgrading of the Teams app. The only scenario a custom value is to be set for this setting is when there are multiple Moodle sites in the organisation, and they all need to be integrated with Teams, thus each site will require a separate Teams app. If custom value is required, please use [https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/new-guid?view=powershell-7 powershell] or [https://www.guidgenerator.com/ external tools] to generate valid ones.
## '''Teams app name''': This allows you to give a custom name, rather than the default "Moodle", to the Moodle Teams app created. It can be useful if you have multiple Moodle sites in your organisation, and each creating a separate Moodle app for Teams integration.
# Once settings are verified, save changes, go back to the tab, and click the "Download manifest file" button to download the new manifest file for the upgraded app.
==== Update Moodle app in Teams ====
# As a tenant admin, go to Teams.
# Go to "Apps" page to manage apps.
# From the menu on the left, click on the link "Built for YOUR ORGANISATION". This should list all custom apps uploaded for your tenant.
# Locate the previous Moodle app, click the options button on the card for more options, and click "update". This should open a file picker.
# Select the new manifest file downloaded from Moodle.
Note that as long as the '''Microsoft app ID for the Moodle Teams app''' setting is not changed, this should be recognised as an app upgrade, rather than uploading a new app. This means that the app will be kept in all existing Teams that have it installed, and all existing Moodle tabs will keep working.

==== Known limitations ====
It is a known issue that if a Microsoft 365 user has never login to Moodle either, her first attempt to SSO from Teams to Moodle will not work silently. Instead, the user will need to click a button from the prompt to login.

=== Single Sign Off ===
When a Microsoft 365 authenticated user clicks the Moodle log out button, it is possible to log the user out from Microsoft 365 at the same time.

In order for this to work, configuration changes in two places are required:
==== Moodle settings change ====
# Sign in Moodle as site admin.
# Go to "OpenID Connect" settings page under Plugins - Authentication:
# Go to "Advanced" tab.
# Enable "Single sign off".
# Save changes.

==== Azure app settings change ====
# Click on the '''Azure Active Directory''' link from '''Azure services''' section, then '''App Registrations''' from '''Manage''' section on the left.
# Locate the app used for Moodle and Microsoft 365 integration, and click its name.
# In the '''Manage''' section on the left of the page, go to '''Authentication'''.
# In the list of '''Redirect URIs''', add the root URL of your Moodle site (wwwroot) as an entry.

== 3.8.0.5 and 3.9.2 release==
3.8.0.5 and 3.9.2 release of the plugins on 18 November 2020 added support for synching the default timezone preference of the user in Outlook to Moodle. This requires the following permission to be granted for the Azure app:
# '''Delegated permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''
# '''Application permissions'''
## '''MailboxSettings.Read'''
## '''MailboxSettings.ReadWrite'''

=Any further questions?=

For support, please open an issue on Github at [https://github.com/Microsoft/o365-moodle/issues]

For community discussion, please post in the [https://moodle.org/mod/forum/view.php?id=8273 Moodle office tool integrations forum] on moodle.org. Note: developers may or may not see questions in this forum thread.

Development:Grades

2021-07-14T13:24:17Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Work in progress}}

== Executive Summary ==

This document primarily describes the current workings of the gradebook. For more detailed information about current gradebook development see [[Development:Gradebook_improvements]]

The gradebook mechanisms must be rebuilt to:

# '''Improve performance and scalability''' - All grades from throughout the system will be pushed to a central system of tables. This means reports based on grades can be generated much faster, and the gradebook has ultimate control over the content.
# '''Improve flexibility''' - All aspects of the new gradebook will use simple plugin structures, namely: exports, imports and displays/reports. It is expected that the community will be very active in producing [[Development:Gradebook Report Tutorial |special-purpose reports]] analysing the basic grade data in new ways, for example, or writing plugins to transfer grades to student information systems.
# '''Allow rubrics for outcomes (aka standards,competencies,goals)''' - As well as numerical grades, each grading item can consist of a number of scores made on a rubric against a standard outcome statement. These can be automatically converted to a numerical grade if desired or just shown as is.
# '''Allow arbitrary columns and derived columns''' - Arbitrary columns of data can be added (either manually or via import). Columns can also be automatically filled based on formulas.
# '''Implement limited public API''' - Activities may use this API to send grades/outcomes to gradebook and find out the final grades.

== Glossary ==

Here are some terms used in the gradebook, both in the development and the user interface. Using these terms in discussions about the gradebook will help to reduce confusion.

{| class="wikitable"
!Term
!Definition
|-
|Activity
|An instance of an activity module [[Category:Modules|Module]] (e.g. a single quiz, assignment etc...)
|-
|Calculation
|A formula used to calculate grades, based (optionally) on other grade items. Not the same as [[Calculated_question_type|Calculated question types]].
|-
|Category
|A set of Grade Items. A Category also has its own aggregated Grade which is calculated from its Grade Items. There is no limit to the level of nesting of Categories (a Category may belong to another Category). However, each Grade Item may belong to only one Category.
|-
|Course completion
|The concept of meeting certain criteria for completing a course. In the context of the gradebook, this means a set of grades that must be reached, or a number of outcomes/competencies to complete/master.
|-
|Grade
|A Grade is a single assessment. It may be a number or an item on a scale (possibly tied to an Outcome). Raw grade value is the numerical or scale grade from activity. Final grade is the grade reported in gradebook.
|-
|[[Gradebook|Gradebook]]
|A central location in Moodle where students' Grades are stored and displayed. Teachers can keep track of their students' progress and organise which set of Grades their students will be able to see. Students see their own Grades.
|-
|Grade Item
|A "column" of Grades. It can be created from a specific Activity or other module, calculated from other Grade Items, or entered manually.
|-
|[[Development:Grades#Locked_grades|Grade Locks]]
|See linked section of this page
|-
|History
|The gradebook has its own type of log, which keeps a History of all changes made to grades.
|-
|[[Development:Outcomes|Outcome]]
|[[Development:Outcomes|Outcomes]] are specific descriptions of what a person is expected to be able to do or understand at the completion of an activity or course. An activity might have more than one outcome, and each may have a grade against it (usually on a scale). Other terms for Outcomes are ''Competencies'' and ''Goals''. See some [[Development:Outcomes_examples|Examples]].
|-
|[[Scales|Scale]]
|A scale is a set of responses from which the teacher can choose one. eg Very cool, Cool, Fairly cool, Not very cool, Not cool
|-
|Letter Grades
|Special representation of grade values similar to scales. Letters are configured in course contexts or above and are defined by lower boundary. eg A (above 90 %), B (above 80 %), C (above 70 %), D (above 50 %), F (above 0 %)

|}

== Database structures ==
=== grade_items ===

This table keeps information about gradeable items (ie columns). If an activity (eg an assignment or quiz) has multiple grade_items associated with it (eg several outcomes and numerical grade), then there will be a corresponding multiple number of rows in this table.

idnumber is a tag unique inside a course identifying the grade item, useful for identifying data in exports and for referring to the grade item in calculations. It is the same as the idnumber in course_modules.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|'''id'''
|int(10)
|
|autoincrementing
|-
|'''courseid'''
|int(10)
|
|The course this item is part of
|-
|'''categoryid'''
|int(10)
|<center>NULL</center>
|the category group this item belongs to
|-
|itemname
|varchar(255)
|<center>NULL</center>
|The name of this item (pushed in by the module or entered by user)
|-
|'''itemtype'''
|varchar(30)
|
|'mod', 'blocks', 'manual', 'course', 'category' etc
|-
|itemmodule
|varchar(30)
|<center>NULL</center>
|'forum', 'quiz', 'csv', etc
|-
|iteminstance
|int(10)
|<center>NULL</center>
|id of the item module
|-
|itemnumber
|int(10)
|<center>NULL</center>
|Can be used to distinguish multiple grades for an activity
|-
|iteminfo
|text
|<center>NULL</center>
|Info and notes about this item XXX
|-
|'''idnumber'''
|varchar(255)
|<center>NULL</center>
|Arbitrary idnumber provided by the module responsible (optional and course unique)
|-
|calculation
|text
|<center>NULL</center>
|Spreadsheet-type formula used to process the raw grades into final grades
|-
|'''gradetype'''
|int(4)
|<center>1</center>
|0 = none, 1 = value, 2 = scale, 3 = text
|-
|grademax
|float(10,5)
|<center>100</center>
|What is the maximum allowable grade?
|-
|grademin
|float(10,5)
|<center>0</center>
|What is the minimum allowable grade?
|-
|'''scaleid'''
|int(10)
|<center>NULL</center>
|If this grade is based on a scale, which one is it?
|-
|'''outcomeid'''
|int(10)
|<center>NULL</center>
|If this is outcome item, which outcome is it?
|-
|gradepass
|float(10,5)
|<center>0</center>
|What grade is needed to pass? grademin <= gradepass <= grademax
|-
|multfactor
|float(10,5)
|<center>1.0</center>
|Multiply all raw grades from activities by this
|-
|plusfactor
|float(10,5)
|<center>0.0</center>
|Add this to all raw grades from activities by this
|-
|aggregationcoef
|float(10,5)
|<center>0.0</center>
|Weight applied to all grades in this grade item during aggregation with other grade items.
|-
|sortorder
|int(10)
|<center>0</center>
|Sorting order of the columns (pre-order walk of the grading tree)
|-
|display
|int(10)
|<center>0</center>
|Display as real grades, percentages (in reference to the minimum and maximum grades) or letters (A, B, C etc..), or course default (0)
|-
|hidden
|int(10)
|<center>0</center>
|1 is hidden, 1 is hide always, > 1 is a date to hide until (prevents viewing of all user grades)
|-
|'''locked'''
|int(10)
|<center>0</center>
|0 is not locked, > 0 is a date when was item locked (no final grade or grade_item updates possible)
|-
|'''locktime'''
|int(10)
|<center>0</center>
|0 no auto locking, > 0 is a date to lock grade item and final grades after automatically
|-
|deleted
|int(10)
|<center>0</center>
|1 means the associated module instance has been deleted
|-
|'''needsupdate'''
|int(10)
|<center>0</center>
|If this flag is set, then the whole column will be recalculated. If set in course item, some other item needs recalculation. Calculated and category items are recalculated together with any other items.
|-
|timecreated
|int(10)
|
|The first time this grade_item was created
|-
|timemodified
|int(10)
|
|The last time this grade_item was modified
|}

=== grade_categories ===

This table keeps information about categories, used for grouping items. An associated grade_item will be maintained for each category to store the aggregate data.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|'''id'''
|int(10)
|
|autoincrementing
|-
|'''courseid'''
|int(10)
|
|The course this grade category is part of
|-
|'''parent'''
|int(10)
|<center>NULL</center>
|Parent grade_category (hierarchical)
|-
|depth
|int(10)
|<center>0</center>
|How deep is this category from the highest level (1,2,3)
|-
|path
|varchar(255)
|
|Shows the path as /1/2/3/
|-
|fullname
|varchar(255)
|
|The name of this grade category
|-
|aggregation
|int(10)
|<center>0</center>
|A constant pointing to one of the predefined aggregation strategies (none, mean,median,sum, etc)
|-
|keephigh
|int(10)
|<center>0</center>
|Keep only the X highest items
|-
|droplow
|int(10)
|<center>0</center>
|Drop the X lowest items
|-
|aggregateonlygraded
|int(1)
|<center>0</center>
|Aggregate only existing grades
|-
|aggregateoutcomes
|int(1)
|<center>0</center>
|Aggregate otcomes together with normal items
|-
|aggregatesubcats
|int(1)
|<center>0</center>
|Aggregate only items placed directly in category or all items in subcategories excluding the subcategory totals
|-
|timecreated
|int(10)
|
|The first time this grade_category was created
|-
|timemodified
|int(10)
|
|The last time this grade_category was modified
|}

=== grade_grades ===

This table keeps individual grades for each user and each item. The raw grade is exactly as imported or submitted by modules. The rawgrademax/min and rawscaleid are stored here to record the values at the time the grade was stored, because teachers might change this for an activity! All the results are normalised/resampled/calculated for the finalgrade, which is relative to the max/min/scaleid values stored in the grade_item. The finalgrade field is effectively a cache and values are rebuilt whenever raw values or the grade_item changes.

Note that the finalgrade for a scale-based item may be non-integer! It needs to be rounded on display.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''
|-
|'''id'''
|int(10)
|
|autoincrementing
|-
|'''itemid'''
|int(10)
|
|The item this grade belongs to
|-
|'''userid'''
|int(10)
|
|The user who this grade is for
|-
|rawgrade
|float(11,10)
|<center>NULL</center>
|The raw grade that came into the system
|-
|rawgrademax
|float(11,10)
|<center>100</center>
|The maximum allowable grade when this was created
|-
|rawgrademin
|float(11,10)
|<center>0</center>
|The minimum allowable grade when this was created
|-
|'''rawscaleid'''
|int(10)
|<center>NULL</center>
|If this grade is based on a scale, which one was it?
|-
|'''usermodified'''
|int(10)
|<center>NULL</center>
|the userid of the person who last modified the raw grade value
|-
|finalgrade
|float(11,10)
|<center>NULL</center>
|The final grade (cached) after all calculations are made. Overriden grades are also stored here.
|-
|hidden
|int(10)
|<center>0</center>
|0 is not hidden, 1 is hide always, > 1 is a date to hide until
|-
|'''locked'''
|int(10)
|<center>0</center>
|0 is not locked, > 0 when was the grade locked
|-
|'''locktime'''
|int(10)
|<center>0</center>
|0 is never, > 0 is a date to lock the final grade after automatically
|-
|exported
|int(10)
|<center>0</center>
|0 is not exported, > 0 is the last exported date
|-
|excluded
|int(10)
|<center>0</center>
|grade excluded from aggregation, > 0 is the last exported date
|-
|overridden
|int(10)
|<center>0</center>
|0 is not overridden, > 0 is the last overridden date
|-
|feedback
|text
|<center>NULL</center>
|Manual feedback from the teacher. Could be a code like 'mi'.
|-
|feedbackformat
|int(10)
|<center>0</center>
|Text format for feedback
|-
|information
|text
|<center>NULL</center>
|not sued yet (Further information like forum rating distribution 4/5/7/0/1 ?)
|-
|informationformat
|int(10)
|<center>0</center>
|Text format for information
|-
|timecreated
|int(10)
|
|temporary hack - the date of submission in activity if any, new field expected in 2.0
|-
|timemodified
|int(10)
|
|temporary hack - the date of grading in activity or date of manual grading in gradebook, new field expected in 2.0
|}

=== grade_outcomes ===

This table describes the outcomes used in the system. An outcome is a statement tied to a rubric scale from low to high, such as “Not met, Borderline, Met” (stored as 0,1 or 2). For more info about these see [[Development:Outcomes]].

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''courseid'''
|int(10)
|<center>NULL</center>
|Mostly these are defined site wide ie NULL

|-
|shortname
|varchar(255)
|
|The short name or code for this outcome statement

|-
|fullname
|text
|
|The full description of the outcome (usually 1 sentence)

|-
|'''scaleid'''
|int(10)
|
|The recommended scale for this outcome.
|-
|description
|text
|<center>NULL</center>
|The full description of the outcome (usually 1 sentence)
|-
|timecreated
|int(10)
|
|the time this outcome was first created

|-
|timemodified
|int(10)
|
|the time this outcome was last updated

|-
|'''usermodified'''
|int(10)
|<center>NULL</center>
|the userid of the person who last modified this outcome
|}

=== grade_outcomes_courses ===
An intersection table used to make standard outcomes available to courses.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''courseid'''
|int(10)
|
|The id of the course being assigned the outcome

|-
|'''outcomeid'''
|int(10)
|
|The id of the outcome being assigned to the course
|}

=== grade_import_newitem ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|itemname
|varchar(255)
|
|*TODO* Document

|-
|importcode
|int(12)
|
|*TODO* Document
|}

=== grade_import_values ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|'''itemid'''
|int(10)
|NULL
|*TODO* Document

|-
|newgradeitem
|int(10)
|NULL
|*TODO* Document

|-
|'''userid'''
|int(10)
|
|*TODO* Document

|-
|finalgrade
|float(10,5)
|NULL
|*TODO* Document

|-
|feedback
|text
|NULL
|*TODO* Document

|-
|importcode
|int(12)
|
|*TODO* Document
|}

=== History tables ===

These table keep track of changes to most of the grade tables. Using these it should be possible to reconstruct the grades at any point in time in the past, or to audit grade changes over time. It should be quicker to use these tables for that, rather than storing this information in the main Moodle log. The following tables are set up for that purpose:

#grade_categories_history
#grade_grades_history
#grade_items_history
#grade_outcomes_history

Each of them has exactly the same DB structure as their matching table (e.g. grade_categories), with 3 extra fields:

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|action
|int(10)
|0
|The action that lead to the change being recorded (insert, update, delete)

|-
|'''oldid'''
|int(10)
|
|The id of the record being changed or inserted (PK of the main table, not the history table)

|-
|source
|varchar(255)
|NULL
|The module from which the action originated
|}

=== grade_letters ===

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Default'''
|'''Info'''

|-
|'''id'''
|int(10)
|
|autoincrementing

|-
|contextid
|int(10)
|
|What contextid does this letter apply to (from levels CONTEXT_SYSTEM, CONTEXT_COURSECAT or CONTEXT_COURSE)

|-
|lowerboundary
|float(10,5)
|
|The lower boundary of the letter. Its upper boundary is the lower boundary of the next highest letter, unless there is none above, in which case it's grademax for that grade_item.

|-
|letter
|varchar(255)
|
|The display value of the letter. Can be any character or string of characters (OK, A, 10% etc..)
|}

== Overview of module communication ==

Modules usually store raw grades internally and pass them into gradebook every time they change. Gradebook may also request activities to resend the grades.

The gradebook is designed to be as separate as possible from the code of activities - modules do not read grade tables or use internal gradebook API.

Originally it was planned to use new events API, but in the end it was decided to use minimal API consisting of several function in lib/gradelib.php and each mod/xxx/lib.php

=== Backward compatibility with Moodle 1.8 and earlier ===

Function grade_grab_legacy_grades($courseid) may be used to request transfer of grades from legacy or 3rd party activities which were not yet converted to new grade API. This function is not called automatically.

Modules are responsible to push existing grades into gradebook during upgrade.

==API for communication with modules/blocks==

Modules may use only functions from lib/gradelib.php which are marked as public. This API may be extended in later 1.9.x release. Activities should access/update only own grades.

===grade_get_grades()===

grade_get_grades($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=0)

Returns grading information for given activity - optionally with users grades. Manual, course or category items can not be queried.

===grade_get_outcomes()===

grade_get_outcomes($courseid, $itemtype, $itemmodule, $iteminstance,$userid=0)

Returns list of outcomes used in course together with current outcomes for this user.

===grade_is_locked()===

grade_is_locked($courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $userid=NULL)

This function will tell a module whether a grade (or grade_item if $userid is not given) is currently locked or not. If it's locked to the current user then the module can print a nice message or prevent editing in the module. If no $userid is given, the method will always return the grade_item's locked state. If a $userid is given, the method will first check the grade_item's locked state (the column). If it is locked, the method will return true no matter the locked state of the specific grade being checked. If unlocked, it will return the locked state of the specific grade.
([http://moodle.org/mod/forum/discuss.php?d=69223#p311329 info])

===grade_update()===

grade_update($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=NULL, $itemdetails=NULL)

Submit new or update grade; update/create grade_item definition. Grade must have userid specified, rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded', missing property or key means do not change existing. Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted'.

===grade_update_outcomes()===

grade_update_outcomes($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data)

Updates outcomes of a given user. Manual outcomes cannot be updated.

== Private gradebook API ==
Private API is used by gradebook plugins and core Moodle code, it may change in 2.0. Most of the interesting classes and functions are in lib/gradelib.php, grade/lib.php and grade/report/lib.php.

The following 3 functions are all in /lib/gradelib.php

===grade_regrade_final_grades()===

grade_regrade_final_grades($courseid=NULL, $userid=NULL, $updated_item=NULL)

Updates all grade_grades->finalgrade records for each grade_item matching the given attributes. The search is further restricted, so that only grade_items that have needs_update == true or that use calculation are retrieved and used for the update. The function returns the number of grade_items updated (NOT the same as the number of grades_grades updated!).

===grade_verify_idnumber()===

grade_verify_idnumber($idnumber, $grade_item = null, $cm = null, $gradeitem)

Verify new value of idnumber - checks for uniqueness of new idnubmers, existing are kept intact.

===remove_course_grades()===

remove_course_grades($courseid, $showfeedback)

Remove all grade related course data - history is kept

TODO: add description of the other methods and classes + simple usage examples + querylib.php description

== Dealing with multiple grades ==

Modules usually produce only one grade item per activity. Optionally one or more outcomes may be attached to activities.

Some activities may need to aggregate multiple ratings or attempts before sending them into the gradebook. Activities can not send variable number of items.

If the gradebook receives multiple grade items from a module, then they are automatically grouped together in a unique grade category (with the same name as the module instance). See [[Development:Outcomes]] for more details.

TODO: this may still be changed

== Calculated grade items ==

Categories or manual items maybe calculated using spreadsheet-like formulas. Formulas may reference other items from the same course only using Id numbers in double square brackets.

eg: <nowiki>= MEAN([[quiz121]], [[quizend]]) + [[assignmentAXC]] + 20.0</nowiki>

== Regrading / updating of final grades ==

TODO: describe needsupdate flag and incremental updates

== Adjustment of raw grades ==
Grade_item contains optional rules for adjusting the raw grade before it is cached into a final grade. These rules are processed BEFORE the calculation discussed above. Scale is never changed. Multfactor and plusfactor may be used to alter raw grades coming from activities, but it is recommended to use formulas instead.

== Displaying the grades to ordinary participants ==

The module takes responsibility for displaying grades within the module (to a student, say). It is recommended to use the real final grades obtained using grade_get_grades() functionBecause guidebook might force hiding, override grade, etc.

For full display of grades in a whole course say, the student uses the same link as teachers use to access the gradebook. However, due to their different permissions they will only have access to specific reports. By default this is the ''User report'' report which only shows their own grades and has very few configuration options.

== Locked grades ==

Both whole columns and individual grades can be locked in the gradebook, via the ''locked'' field. Teachers may want to do this to prevent further changes from the modules, or from other teachers. When a grade is locked, any changes that might affect that grade are ignored. When the graded is unlocked, activities are asked to resend the latest grades.

In the main GUIs the lock toggling will be achieved by clicking on a little padlock icon beside each entry or column.

There is also an option to lock grade or item after some specified date.

== Overridden grades ==

Grades can be manually modified (overridden) in the gradebook. When this is done the entered value is always used instead of the aggregated, calculated or activity grade.

Once grades have been overriden in the gradebook they become read only in the original module. The module should provide a visual indication as to why the grade cannot be modified.

The need to improve how the module expresses that a grade has been overridden will be reduced by the new [https://docs.moodle.org/en/Development:Grading_interface_2.0 grading interface]

== Hidden grades and categories ==

Grades and categories can be hidden in the gradebook or the "categories and items" screen. When a category is hidden all the grade items within it are automatically hidden as well. When a category is un-hidden then all the grade items within it are un-hidden.

The teacher always sees totals calculated from all relevant items (hidden or un-hidden)

(Features below were added in 1.9.8 and 2.0)

When a grade is shown its parent category will also be shown if it was hidden. MDL-21367

The teacher decides what ordinary users can see in the case of totals that include hidden grades (MDL-21218, in 1.9.8 and 2.0). The user and overview report each have a setting to choose between:

# Hide any totals that are dependent on a hidden item (show a hyphen there) [DEFAULT]
# Display totals excluding the hidden items
# Display full totals including the hidden items (may allow students to back-calculate hidden grades)

== Logging ==

All grading related changes maybe logged in history tables.

== Security Issues ==

For security an option to force SSL for the gradebook might be good.

==Overall grade==

Each course has exactly one course grade item. It may be used for this purpose now. Other course completion criteria will be implemented in 2.0.

== Report plugins ==
All the main interface of the gradebook are implemented as report plugins. Each plugin is fully responsible for page layout, there are some handy functions in grade/lib.php. They can even define their own capabilities and extra tables if the core tables are not enough, as they'll have a full /grade/report/xxxx/db directory.

Each report defines one capability to allow people to see that report, so that admins have control over who can see what reports. For example, the participant interface can be a totally separate report plugin.

This allows for the widest flexibility and safety in how grades are presented.

=== Default teacher interface ===
This interface will be what teachers see by default, and will subsume everything the current interface (in Moodle 1.8) does.

Some snippets of functionality:
{{Moodle 1.9}}
Overall it's a grid, with participant names down one side and grade items along the top.

Columns will be able to be collapsed together by grouping them into categories. Grades for categories can be calculated via various means.

“Eye-cons” on the columns and checkboxes by every grade (this bit possibly controlled with a switch) allow hiding by category, by column, by individual grade.

Textual notes can be added to each grade for more info. These show up to participants as well.

A groups menu allows the teacher to switch between showing EACH of the groups they have access to, or ALL the groups they have access to.

All grade items will link to modulepath/grade.php?id=44 which will work out what the current person should be allowed to see and either redirect them to the correct page or just show them immediately. This copes with situations like the quiz, say, where we want editing teachers to go to the detailed reports there while participants just see their own grade or whatever the quiz is set to show.

User preference to SWITCH between showing raw grades, percentage grades, or both, or grade letters (A/B/C etc).

Settings for grade letters not only define the transformation from percentage to grades, but also the transformation from letters to grades (in case the teacher edits some of the letter grades).

Categories are shown above the headings for each column. Clicking for more info on a category will just show the category with a summary column showing total/average for just that category (PLUS the summary column for the whole course).

All columns should be sortable up/down.

At the bottom of each column is a row with the mean course score. If in groups mode, then add ANOTHER row with just the group mean. Add the number of grades used in brackets. eg 56% (11). When the report is paged, these means are still for the whole course/group (not the page!)

{{Moodle 2.0}}

Teachers can type “straight into” the grid using AJAX or fallback to forms. No popup menus for values.

Later on we can support customisable shorthand codes to make data entry quick (eg type 'ab' for absent, or 'nge' for not good enough).

See [http://test.moodle.com/grade/report/grader/index.php?id=2 the test site] for a live demo of this report.

=== Default participant interface ===
This interface will be what participants see by default:

Some snippets of functionality:

*Invert the grid to show one item per row, with the total/average at the bottom.
*Use second/third columns to show categories.
*Include ranking score in another column.
*Show feedback
*Show percentage
*No editing functionality.

See [http://test.moodle.com/grade/report/user/index.php?id=2 the test site] for a live demo of this report.

=== Outcomes report ===
This simple informational report displays all the outcomes used by the course, with the following information:

*Outcome name
*Overall average: If the outcome is used by more than one activity, this shows you the mean across all these activities in the current course
*Site-wide: Yes or No: A site-wide outcome is automatically made available to all courses.
*Activities: A list of links to the activities in the current course that use each outcome. One row per activity (table splits here)
*Average: For each activity using the outcome, the average score is shown.
*Number of grades: For each activity using the outcome, the number of grades is shown (non-graded participants are ignored)

See [http://test.moodle.com/grade/report/outcomes/index.php?id=2 the test site] for a live demo of this report.

=== Overview report ===
Another basic report, showing a participant's course averages in each of the courses in which s/he has received grades.

See [http://test.moodle.com/grade/report/overview/index.php the test site] for a live demo of this report.

== Export plugins ==

The API for these is extremely simple. Each export plugin should occupy a directory under /grade/export/xyz and needs to provide only an index.php file as a the primary interface. This file just accepts a 'courseid' parameter.

== Import plugins ==

Each import plugin should occupy a directory under /grade/import/xyz and needs to provide only an index.php file as a the primary interface. This file just accepts a 'courseid' parameter.

The index.php will show an interface for further options and selections.

Import plugin must validate data before starting the import operation, if some parts of import fail the user must be notified.

Some sample import plugins are:

===Import from CSV===

Accepts an upload of (or URL to) a CSV file. Multiple options describe how to process the file, which columns to add etc. The imported grades always override current grades.

===Import from XML===

Accepts an upload of (or URL to) an XML file with this kind of format (from OU).

<results batch="[someuniqueimportnumber]">
<result>
<state>['new' or 'regrade']</state>
<assignment>[idnumber]</assignment>
<student>[studentid]</student>
<score>[score]</score>
</result>
<result>
<state>['new' or 'regrade']</state>
<assignment>[idnumber]</assignment>
<student>[studentid]</student>
<score>[score]</score>
</result>
[...]
</results>

== Capabilities and Permissions ==

* moodle/grade:view - view own grades or grades of other user if used in CONTEXT_USER

* moodle/grade:viewall - view grades of all users

* moodle/grade:viewhidden - see grades that are marked as hidden for the owner

* moodle/grade:hide - be able to hide/unhide cells, items or categories

* moodle/grade:lock - be able to lock cells, items or categories

* moodle/grade:unlock - be able to unlock cells, items or categories

* moodle/grade:manage - manage grade items and categories in gradebook (create, edit, lock, hide, delete, etc.)

* moodle/grade:import - general import grades, requires separate permission for each plugin

* moodle/grade:export - export grades, requires separate permission for each plugin

* gradereport/grader:view - can view the grader report

* gradeimport/csv:view - can view/use the csv import plugin

* gradeexport/csv:view - can view/use the csv export plugin

* moodle:site/accessallgroups

== Development Tasks and Tracking ==

For details of 1.9 development see [http://tracker.moodle.org/browse/MDL-9137 MDL-9137]

For details of 2.0 development see [https://docs.moodle.org/en/Development:Gradebook_improvements Gradebook_imporovements] and [http://tracker.moodle.org/browse/MDL-19131 MDL-19131]

==Updating module code==
Module authors must implement new gradebook API and add upgrade code for migration of old grades into new gradebook. Fortunately the needed changes are not big.

Steps:
*add xxx_update_grades() function into mod/xxx/lib.php
*add xxx_grade_item_update() function into mod/xxx/lib.php
*patch xxx_update_instance(), xxx_add_instance() and xxx_delete_instance() to call xxx_grade_item_update()
*patch all places of code that change grade values to call xxx_update_grades()
*patch code that displays grades to students to use final grades from the gradebook

There are many examples in official modules, assignment has the most advanced implementation.

== Ideas for the future ==
{{Moodle 2.1}}
See [[Development:Gradebook_improvements]] and MDL-25423 for details of planned future enhancements

*option to aggregate including/excluding hidden grades - needs db changes
*option to rollback all changes during import operation if anything fails
*performance improvements
*conditional activities
*course completion criteria
*better public API for modules
*better API for gradebook plugins
*better state tracking in export plugins
*ajax reports
*specialised reports
*submission and marking date tracking db changes
*calculation formula improvements
*historical views
*individual graph of grades (time vs %). Bar graph, lineal graph. Add (or not) the maximum posible; line of 0 (=minimum), 25, 50 (=median), 75 and 100 (=max) percentils of the group

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69223&mode=3 Gradebook Development ideas] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=51107 New gradebook for Moodle] forum discussion
* [[Development:Gradebook Report Tutorial]]

[[Category:Developer|Grades]]
[[Category:Grades]]

Development:Survey 2 brainstorm

2021-07-14T13:24:17Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survey1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (custom html and css, as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
* email submissions to address specified in a designated question field (for surveys not requiring login)
* for text fields, simple data checking ('must be numeric', 'must contain X character', 'must have exact length n', etc.)
* full web accessibility features to the same level as elsewhere in Moodle e.g. labels on text fields, fieldsets on groups of radio buttons & checkboxes.
* gradebook integration (to allow simple polls to control conditional activities)

==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="wikitable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
* option whether to show results immediately after submission, or a thank you message with link to results.

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* report per survey, per user and per question
* report about non-respondent users
* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use [maybe later]
* question sets can be used across multiple courses [maybe later]
* questions can be re-ordered within an activity
* question sets can be combined to create a template
* questions can be deleted from an activity, but there should be an "are you sure" check first.

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Mindmap module

2021-07-14T13:24:17Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{stub}}
This contributed code activity module can add, create and share mindmaps within Moodle.

==Features==
* Create and share mindmaps online.
* Make mindmaps public or share them with groups or make them public.
* Export maps to XML, PDF, image or Freemind-files.
* Edit mindmaps offline via Gears or Adobe AIR

Most important commands and functions
{|class="wikitable"
! Function
! Command
|-
|add node
|
*Doubleclick on any place or click the green plus-icon
*ENTER adds a node to the same layer
*INSERT adds a childnode
|-
| delete nodes
|
* CTRL + click on the node,
* press DELETE
* click the red minus-sign
|-
|deletes a node and all of his child-nodes
|CTRL + D
|-
|Undo and Redo
|
*CTRL + Z and CTRL + Y or
*use the icons|
|-
|Autocomplete-Node
|press END
|-
|move node
|
#position a node over new parent,
#release mouse,
#reposition node
|}
For Mac User: There is no INSERT key! To add a childnode on Mac, first highlight the mother node. Then while pressing command key, double tab at the new position for the childnode. Or if you are using the mouse position your cursor at the new childnode place, then double click left mouse at the same time pressing the command key.

==See also==
*[http://moodle.org/mod/data/view.php?d=13&rid=1628 Mindmap] is a Modules and plugins database page for downloads and more information.
*Discussions: please create or find a discussion topic in the [http://moodle.org/mod/forum/view.php?id=44 Contributed Code forum]
*[[FreeMind filter]] contributed code

* Register here to find out more about: http://ekpenso.com/
[[Category:Contributed code]]

Development:Community hub

2021-07-14T13:24:11Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Moodle 2.0}}

* '''PROJECT STATE: implemented'''
* '''MAIN TRACKER ISSUE''': MDL-19309
* '''DISCUSSION AND COMMENTS''': [http://moodle.org/mod/forum/view.php?id=7330 Hub servers] forum in Using Moodle
* '''MAIN AUTHORS''': [[User:Martin_Dougiamas|Martin Dougiamas]] and [[User:jerome_mouneyrac|Jerome Mouneyrac]]

This page describes an overall functional specification for the "Moodle Community Hub" project, which consists of a new system (the Moodle Hub Server) and several new features in Moodle 2.0.

= Goals and rationale =

The main goals of the Community hub project are:

# to allow people to easily find courses around the world that they want to enrol in:
#* educators want to find '''communities of practice''' that are subject or region-oriented, so that they can associate with their peers on a long-term basis.
#* other learners want to find and study courses on various other subjects
# to make it easy for educators to find and download '''course templates''' from other people. This will help educators share and identify examples of '''best practice''' in online pedagogy and hopefully improve the average quality of online courses.

Finally, we want to do all this in the simplest, safest way possible, while allowing a range of scenarios such as courses that are public or private, free or paid, so that the Moodle community can build solutions for themselves.

= Overview =

The diagram below shows the basic idea. The systems in this diagram are:

;Ordinary Moodle site: A typical Moodle site with teachers who want to download course templates and/or users who want to connect (enrol) with external communities
;Publishing site: A Moodle site that wants to make some of its courses available for download
;Community site: A Moodle site that provides courses that are enrollable
;Moodle Hub Server: A new Moodle plugin for listing registered courses that are '''downloadable''' or '''enrollable'''. The default hub will be installed at hub.moodle.org, but there can be many others.

[[Image:Community-hubs-flowchart.png]]

Downloadable courses
* (A) Sites that want to publish certain courses and make them downloadable can register them with one or more Hub Servers.
* (B) The Hub will check the data and make sure the course zip is downloadable, caching a copy locally. The Hub may also have a security process to check the download for trojan horses, bad content, etc.
* (C) The download process may trigger the backup process on the original server if it hasn't been done already.
* (D) Later, Moodle users (who have permissions to do so) can connect to a Hub to search for downloadable courses and choose one.
* (E) The Moodle site downloads the file and makes it available to the Moodle user so they can now continue to restore it normally.

Enrollable courses
* (1) Sites that want to publish certain courses for the public to enrol in can register them with one or more hub (including the main one at moodle.org)
* (2) Later, any Moodle user can connect to a hub (via Community block in their site) to search and find courses they want to join
* (3) They click on a link to be sent to the other site so that they can enrol there.

= Use Cases =

== New teacher creating a course ==

# New teacher needs some help with a new course for "Alligator farming 101"
# Teacher sees the "Community" block into the "Alligator farming 101" course page and presses "Search course"
# Teacher browses a list of downloadable courses in the community page (the data comes from one or more Hubs via web services)
# Teacher searches for "Alligator"
# Teacher finds 4 courses that look good, and after reading reviews and ratings, chooses one.
# The course is downloaded and unpacked in Moodle.
# The teacher now has a good starter course they can keep developing.

== New teacher needs help ==

A teacher decides they need some help and wants to talk with others teaching Alligator farming.

# Teacher goes to their "Community" block and clicks "Search course".
# Moodle displays a page to search for courses (the data comes from one or more Hubs via web services)
# Teacher searches courses for "educator" courses on "Alligators" in their country/language.
# Teacher finds two, selects one, and is returned to the page where is was before clicking on "Search course". The selected course is now permanently listed in the Community block.
# Teacher clicks on the link and is taken to the course, where they can enrol and interact/learn with peers over time, subscribe to forums etc.

== University consortium ==

A group of five universites wants to share courses among themselves and not to the outside world. They also want to prevent teachers from downloading courses from outside the consortium.

# Someone downloads Moodle and installs it as a private Moodle Hub Server
# Admins of all five Moodle sites in the group add the URL of the private Hub to their settings and register their sites there
# The default Hub at hub.moodle.org is (optionally) disabled in the site-wide settings.
# Admins register their courses with the Hub.
# Teachers can now import, export or join courses via the private Hub.

== Course creation business ==
NOT IMPLEMENTED

CoolCourses Inc have produced a set of 50 good Moodle courses which they wish to sell.

# They set up a Moodle site with all their courses in them.
# They set up a Hub with a payment system, and register it with the Hub List at moodle.org so people can find it
# They register all their courses with their own Hub with appropriate metadata
# When looking for courses, users can either
#* find this Hub by browsing through the Hub List, or
#* type the URL of the Hub directly into their Moodle site
# When users try to download a course, they may see a payment button to download it (credit card, paypal etc)
# CoolCourses could provide limited access to the courses on their Moodle site using Roles, as a preview.

= Components =

There are several components:

;'''Hub List''': A list of known Hub Servers, kept on moodle.org
;'''Hub Server''': A new Moodle plugin for publishing a list of registered courses that are '''downloadable''' or '''enrollable'''
;'''Course registration''': A new mechanism in every Moodle to register particular courses with one or more Hub Servers
;'''Community membership block''': to search Hub Servers to find enrollable courses to join and bookmark
;'''Import/Export block''': Makes it easy to find downloadable course templates in a Hub Server, then download them from the Hub Server and restore them locally

==Moodle Hub List==
The Hub List is a list of known Hub Servers (see the next section). This makes it easy for Moodle users to find the most appropriate Hub Servers for their needs. To get on the Hub List, Hub Servers choose to register with moodle.org via their administration interface.

Moodle.org will store the following information, and make it available via a browseable interface at [http://hubdirectory.moodle.org/ hhttp://hubdirectory.moodle.org/].

==Moodle Hub Server==
[[Image:Registerhub.png| thumb |Mockup: hub registration page]]
The Moodle Hub Server (aka Hub) is a separate system (based on Moodle technology) that allows Moodle sites to register their courses for listing there. More technically, the hub server is a Moodle plugin.

A default installation of this software will be running at '''hub.moodle.org''', but anyone else can download it and set up their own hub for private or public uses. A hub can also be used as a Moodle site, even though the Moodle front page will be replaced by the hub front page.

Hubs can optionally register themselves in the Hub List so that they are easier to find and so they can become a "Trusted Hub".

A hub server has some config fields (saved into its database):
* name (site name by default, changing the value here, do not change the site name)
* description (front page summary as default value)
* language (choose the language, set site language as default)
* contact name (current user by default)
* contact email
* enable
* password (only for private hub)
* logo url (need to have a limited size of 150x150)
* protected web search interface '''(TODO: MDL-24015)'''

=== Data structure ===
Most of the data structure can be found in the [https://docs.moodle.org/en/Development:Community_hub_-_technical_specification community hub technical specification].

=== User interface ===
[[Image:Webinterface.png|thumb|Mockup: search course UI]]
If visiting the hub via the web, it will provide an interface for full searching and browsing.

The web interface can be protected from access. The hub at moodle.org will of course be open to all.

[[Image:Search_hub_moodle.png|thumb|Mockup: search hub UI]]

The web interface allows users to:

* search by keyword (descriptions, titles, tags, subject etc)
* browse a list of courses by subject
* go directly to a course (if marked for public use)
* preview a course (if screenshots have been provided, or the original URL location)
* download the course to desktop (only if an download url has been set)
* If logged in to the Hub, users can also:
** give a rating to the course
** write a comment for the course - <span style=color:blue>use comment 2.0 API</span>

When displaying courses, you can see and sort by:

* Title - ''Sortable''
* Description
* Tags - ''Sortable <span style=color:blue>(first tag retrieved by the request is considered)</span>''
* Screenshot(s)
* Cost (if any) - ''Sortable''
* Rating (10-point scale displayed as 5 stars, and only if you are logged in to moodle.org) - ''Sortable''
* Comments
* Moodle site name
* Date added to directory
* Date last updated in directory
* Audience (teachers, students, admins)
* Teacher name(s) - ''Sortable''

=== Web service interface ===
'''TODO: MDL-24031'''
A REST-based web services interface will be provided for other systems (eg Moodle sites) to use directly.

Web services can search on:
* string search
* array language
* array cost
* array Moodle url
* Others?

=== Hub admin interface ===

The hub will have a Hub admin interface. Admin processes include:

* Listing, approving and editing the sites registered with the hub
* Listing, approving and editing the course descriptions, metadata etc.
* Registering/updating the Hub with the Hub List
* Configuring Hub behaviour and the appearance of the home page.

== Course global search functionality ==
In order to quickly search a course on all public hubs, Moodle.org will have a table equivalent to the course 'directory' table with dew additional field as "public hub id", "site url", "site name"...

== Site registration ==
[[Image:SiteRegistration.png|thumb|Mockup: site registration UI]]
The existing site registration form in Moodle will be extended so that admins can:

# choose one or more Hubs to register with (hub.moodle.org and/or others in the Hub List, or directly to a particular Hub specified by URL)
# choose to enable cron to re-send statistics to the hub on a periodic basis. (TODO/TBD)
# choose to enable the hub to harvest courses on a periodic basis (TODO: not shown on image/TBD)

== Community membership ==

The "Community" block allows people to find and subscribe to external courses that they want to be part of.

Visibility of the block and the features within it are controlled by roles, and contains:

# 'Bookmarks' of previously-selected (subscribed) external courses (to make revisiting easy) grouped by site, which can be edited/deleted etc
# A link to a search script - "Add new courses..."
# A search script to browse/search one or more Hubs (via web services to get the data, with the interface rendered by the local script). Users can select joinable courses from the list and they'll get added to the list in the block.

Generally the links will be just be an ordinary URL and the remote site will be responsible for authentication.

If the foreign site has an Mnet connection set up with the current site then login will be immediate.

[[Image:Addacourse.png|thumb|Mockup: community block]]

community block database structure:
{| class="wikitable"
|-
! Name
! Type
! Description
|-
|id
|int
|Standard autoincrement
|-
|userid
|int
|foreign key - ID of the user
|-
|-
|coursename
|varchar
|Name of the community course
|-
|coursedescription
|text
|Description of the community course - display by the tag link
|-
|courseurl
|varchar
|The full URL to the community course front page
|-
|image
|varchar
|community course logo url - it could be displayed as icon
|}

== Publish courses ==
'''Publish course''': to publish or update the description of the current course in one or more Hubs

The '''Publish''' button only exists if the current user has the appropriate capabilities and if the current Moodle site has been registered with a Hub.

[[Image:Coursepublishing.png|thumb|Mockup: course publishing]]

Choosing "Publish" goes to a script where you can chose from the registered Hubs and whether you want to publish the course as:
* enrollable/advertise, so that others can come here and use the course where it is, and/or
* downloadable/share, so that a Hub can offer this course for download to others

If the user wants to offer this course for download, then they are directed to the standard backup process to create and define the backup file (without users!). If the backup is successful the zip is stored in a standard place and then the user is returned to the publish script to continue. (If downloads are not required then this whole step is skipped).

It allows the user to set up full , and especially whether you want to advertise this course as being:

Now the script presents a form with metadata that this course will be published with on the chosen Hub(s) (this is also available in the course settings page). Metadata includes information such as description, licensing, categories, screenshots etc (see the [[#Courses|Courses]] section above for more info).

After checking/updating the metadata, the script will push the data to the selected Hub.

If the checkbox to allow download was selected, then the URL to a course upload script in the current Moodle is included with the metadata. This URL contains a token (eg an MD5 stored in the course table) that only the Hub knows.

The course upload script (eg /local/hub/webservice/upload.php?id=55&token=XXXXX) will expect the cached .zip file for the given course.

==== Publish course settings ====

Some publish settings and info will also be available anytime via the course settings page under a "Publish" tab:

* Which hubs has this course been published on, and when
* Full metadata
* Screenshots

== Harvest courses ==
'''NOT IMPLEMENTED'''
''Note: site to hub communication is one way only, the following text may change.''

Each hub will use cron to call every site that has registered a harvesting url on a periodic basis. This will be done at the same time as the link is checked to ensure the site is reachable, so the "time link was last checked" field in the site table also indicates when the site was last harvested.

The harvesting url will be an RSS feed which will list all the courses to be included in the hub and their metadata. This might be the feed of all visible courses on the site, or courses in a given category. TODO: should we allow them to enter multiple category feeds so they can say "arts", "business" and "languages" but not "science"?

Course list RSS feeds are an existing tracker item for Moodle 2.0 See http://tracker.moodle.org/browse/MDL-13248 This patch allows admins to pick which categories have individual feeds created and are included in the "all courses" feed. Each course becomes an <item> in the RSS feed as follows:

* <category> the Moodle course category in which the course belongs
* <title> the course fullname
* <link> the course url
* <pubdate> the date the course (or any of its resources and activities) last updated
* <description> the course summary

The current tracker item will need to be extended to include appropriate course metadata in the RSS feed. There is a [http://purl.org/dc/elements/1.1/ Dublin Core extension to RSS 2.0] which can be implemented.

TODO: If we choose an alternative metadata format we will need to locate or create an alternative RSS extension. There is a [http://www.downes.ca/xml/RSS_LOM.htm LOM extension] but not from an official IEEE namespace.

We will need to declare our own namespace RSS extension to identify whether a course should be listed in the hub as downloadable and/or enrollable. This extension will add tags to the RSS feed as follows:

* <moodlehub:downloadable>
* <moodlehub:enrollable>

Both tags will take either "yes" or "no" values and will be set by course creators at the same time as they enter course metadata.

The hub will check the published date for each item in the RSS feed to identify whether it needs to update its records. TODO: if we use OAI-PMH for harvesting we can request courses updated since x see http://moodle.org/mod/forum/discuss.php?d=127488

If the course has been updated and is <moodlehub:downloadable> is yes, then the hub will request the site to create a new backup of the entire course (less user data).

= See also =
* [https://docs.moodle.org/en/Community_hub Community hub]
* [https://docs.moodle.org/en/Development:Community_hub_-_technical_specification Development: community hub technical specification]

[[Category:Hub]]

[[ja:開発:コミュニティハブ]]

Development:Ratings 2.0

2021-07-14T13:24:11Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Moodle 2.0}}==Objectives==

Ratings are grades entered away from the gradebook. They can be entered by students and teachers and are aggregated into grades.

The goals of ratings 2.0:

* Manage ratings centrally
* Use a consistent approach for all ratings throughout Moodle
* Easily integrate ratings 2.0 with existing modules
* Remove duplicate implementations of ratings functionality

==Overview==

The ratings 2.0 provides APIs to:
# Add ratings
# Update ratings
# Access collected ratings for grade calculation purposes
# Delete ratings

==Current tracker issues==
MDL-21389 Write spec for separate Ratings 2.0

MDL-20514 Allow Aggregate Type in Glossary Activity

MDL-21657 Implement Ratings 2.0

==Interface==

[[Image:RatingUI.gif]]

When Javascript is enabled ajax submission means the button can be removed. In the future it would be possible to automatically interpret a 1 to 5 rating as a star rating style UI element.

If the user has 'post' permission as returned by modname_rating_permissions() the dropdown box and submission button will be displayed.

If the user has 'view' permissions the text to the left of the dropdown box will be displayed. The displayed text consists of the aggregate of the ratings, 4 out of 5 in the example. The number in brackets is the number of ratings that have been submitted. There have been two ratings submitted in the example.

If the user has 'viewall' permissions they can click on the aggregate summary to view a list of all of the ratings that have been submitted. This is a listing of each user's profile pic, their name and the rating they submitted.

==Database changes==
===New tables===

====Ratings====

{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this comment.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of plugin owning the comment.
|-
| itemid
| int(10)
|
| Some plugin specific item id (eg. forum post blog entry)
|-
| scaleid
| int(10)
|
| ID of the scale (1-5, 0-100, custom) from which the user selected their rating. Including this allows smarter handling of previously entered ratings should the scales be changed.
|-
| rating
| int(10)
|
| The user's rating
|-
| userid
| int(10)
|
| The user who submitted the rating
|-
| timecreated
| int(10)
|
|
|-
| timemodified
| int(10)
|
|
|}

===Altered tables===
The forum, glossary and data tables need to be altered to contain the required fields specificed in [https://docs.moodle.org/en/Development:Ratings_2.0#Ratings_Settings]

===Removed database tables===

The following tables will have their data migrated to the above ratings table and then be removed:

data_ratings

forum_ratings

glossary_ratings

===Scales===

Course modules will continue to store the scale associated with their ratings. For example the glossary table has a scale column.

Scales are going to be refactored as part of a separate issue. See MDL-17258.

==Ratings code changes==

rating/lib.php will contain...

===class rating===

====__construct($options)====

Initialize a class instance. Requires context, itemid, scaleid and userid.

====update_rating($rating)====

Add or update the numerical value of the rating in the database

====get_rating()====

get the numerical value of the rating

====delete_rating()====

delete the rating. Not implemented yet as it hasn't been required.

===class rating_manager===

====public get_ratings($options)====
Returns the supplied set of items with a rating instance attached to each item.

$items is an array of objects with an id member variable ie $items[0]->id.
$options requires context, items, aggregate and scaleid.

items is an array of items such as forum posts or glossary items. They must have an 'id' member ie $items[0]->id.
aggregate is the the aggregation method to apply. RATING_AGGREGATE_AVERAGE etc.

Optionally options may include userid, returnurl, assesstimestart and assesstimefinish.

If userid is omitted the current user's id will be used.
returnurl is the url to return the user to after submitting a rating. Can be left null for ajax requests.
assesstimestart. Only allow rating of items created after this timestamp.
assesstimefinish. Only allow rating of items created before this timestamp.

<code php>
function get_ratings($options) {
global $DB, $USER;

if (isnull($userid)) {
$userid = $USER->id;
}

$itemids = array();
foreach($items as $item) {
$itemids[] = $item->id;
}

list($itemidtest, $params) = $DB->get_in_or_equal(
$itemids, SQL_PARAMS_NAMED, 'itemid0000');

$sql = "SELECT r.itemid, ur.id, ur.userid, ur.scaleid,
$aggregatestr(r.rating) AS aggrrating,
COUNT(r.rating) AS numratings,
ur.rating AS usersrating
FROM {ratings} r
LEFT JOIN {ratings} ur ON ur.contextid = r.contextid AND
ur.itemid = r.itemid AND
ur.userid = :userid
WHERE
r.contextid = :contextid AND
r.itemid $itemidtest
GROUP BY r.itemid, ur.rating
ORDER BY r.itemid";

$params['userid'] = $userid;
$params['contextid'] = $context->id;

//add ratings to the items at $item->rating. Similar to make_context_subobj().
//Iterate over forum $items (forum posts, glossary items etc) and create the $item->rating objects. Properties of the individual ratings, such as $item->rating->aggregate and $item->rating->rating, are stored on the rating object directly.
//Settings common to the ratings are stored at $item->rating->settings->aggregationmethod (for example).
}
</code>

====get_aggregation_method($aggregate)====
Converts the aggregation method constants to a string that can be included in SQL

====get_all_ratings_for_item($options)====
Load all ratings for a given item. Used to display a listing of submitted ratings to users with 'viewall' permission.

Requires context, itemid and optionally accepts an SQL order by clause.

====get_user_grades($options)====
Returns a grade for a user based on other user's rating of their items.

===Rendering ratings===

As rendering a rating will consist of only a single function call a new method called render_rating() will be added to the core renderer.

If necessary a ratings renderer could be added. Located in mod/ratings/renderer.php this new class core_rating_renderer should extend plugin_renderer_base defined in lib/outputrenderers.php Almost all renderers appear to inherit from plugin_renderer_base rather than core_renderer.

=====core_renderer::render_rating(rating $rating)=====

returns rating UI html snippet. Used to include ratings in pages.

===Using the rating renderer===

The process to render ratings is as follows:

<code php>
// in mod/forum/discuss.php (for example)
$posts = // Some forum/lib.php function call.

//these are supplied by the calling module (forum etc)
$aggregate =
$scaleid =
$userid =
$returnurl =

//The current scaleid comes from the forum or glossary object and may be changed at any time so supply it each time
//Also, a user should only see their own ratings
$posts = rating::load_ratings($context,
$posts/* Optional array of items (forum posts or glossary items) with an 'id' property. If null returns all ratings for the context by the user*/,
$aggregate,
$scaleid,
$userid,
$returnurl);

//ratings are now attached to the post objects. $posts[0]->rating

foreach ($posts as $postid => $post) {
$forumoutput->post($post);//access the rating info at $post->rating, $post->rating->aggregate and $post->rating->count
}

// in mod/forum/renderer.php, in the post($post) method:

// ... output most of the post ... starts around line 5813 of mod/forum/lib.php
echo $OUTPUT->render($item->rating);
// ... output the rest.

// and finally in rating/lib.php in the rating class:

public function core_renderer::render_rating(rating $rating) {
//return html representation of the rating
}
</code>

===Ratings Aggregation===
Forums currently support multiple forms of rating aggregation such as average, maximum, sum etc. These options should be available everywhere that ratings are available.

They are calculated within rating::ratings_load_ratings()

===Ratings Settings===
Settings for ratings are stored by the module. Each module table, for example forum, must contain the following columns.

{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| assessed
| int(10)
|
| The aggregation method to apply. A value of 0 means ratings should be disabled. Currently the glossary stores an "allcanrate" flag in the assessed column. "allcanrate" will disappear in favour of proper permissions.
|-
| assesstimestart
| int(10)
|
| From when can users submit ratings
|-
| assesstimefinish
| int(10)
|
| When must users submit ratings by
|-
| scale
| int(10)
|
| What scale to use
|}

The "Restrict ratings to posts with dates in this range" flag is calculated in the course/moodleforum_mod.php method moodleform::data_preprocessing() and is not stored in the database.

====Settings interface====
=====moodleform_mod::standard_coursemodule_elements()=====
Adds elements to an instance of moodle form. The ratings elements should appear in a separate block from Common Module Settings.

It will determine whether to include ratings settings by calling plugin_supports() found in lib/moodlelib.php like this...
<code php>
if (plugin_supports('mod', $this->_modname, FEATURE_RATINGS, false)) {
//include ratings elements
}
</code>

mod/%modulename%/lib.php defines a function called %modulename%_supports() that lists the elements that the module supports.

FEATURE_MOD_RATINGS will have to be added to lib/moodlelib.php

===Rating Submission===

rating/rate.php will be the target for posted ratings. Previously each module implemented their own ratings submission. For example mod/glossary/rate.php within the glossary module.

The supplied fields should consist of
{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| contextid
| PARAM_INT
|
| The context id defined in context table - identifies the instance of plugin owning the comment.
|-
| itemid
| PARAM_INT
|
| Some plugin specific item id (eg. forum post blog entry)
|-
| scaleid
| PARAM_INT
|
| ID of the scale (1-5, 0-100, custom) from which the user selected their rating. Including this allows smarter handling of scales being changed.
|-
| rating
| PARAM_INT
|
| for example, in user profile, you can comment user's description or interests, but they share the same itemid(==userid), we need comment_area to separate them
|-
| returnurl
| PARAM_LOCALURL
|
| Null for ajax requests. If not null the url to which the user should be redirected after recording the rating
|}

The process to record a rating is as follows:

<code php>
$permissions = forum_rating_permission();
if($permissions['post']) {
$rating = N; //the actual rating from the user
$ratingObj = new rating($contextid, $scaleid, $userid, array($itemid));
$ratingObj->set_rating($rating);
//redirect to return url if supplied
}

//within the class rating
function Rating::update_rating($rating) {
$ratings = rating_system::load_ratings($scaleid, $userid, $contextid, array($itemid));
if( !$ratings || sizeof($ratings)==0) {
$data->contextid = $this->contextid;
$data->scaleid = $this->scaleid;
$data->userid = $this->userid;
$data->rating = $rating;
$DB->insert_record($this->table, $data);
}
else {
$data->id = $this->id;
$data->rating = $rating;
$DB->update_record($this->table, $data);
}

}
</code>

====Ajax submission====
Ajax submission of ratings must be possible for sites with ajax enabled. ForumNG (http://moodle.org/mod/data/view.php?d=13&rid=2927) written by Sam Marshall contains an ajax implementation of the rating UI elements that may be useful to reference.

Check if ajax is enabled like this...
<code php>
if (empty($CFG->enableajax)) {
//no ajax
}
else {
//add ajax stuff
}
</code>

=== Permissions changes ===

Ratings is dependent on two things: core capabilities and the result of a module callback (which may itself use module capabilities).

====New ratings permissions====

New system-wide ratings permissions will be added. These will be checked IN ADDITION to local permissions in existing modules.

It is anticipated most new modules will just use these.

The new capabilities are:

moodle/rating:view - allows the user to view aggregated ratings made on their own items

moodle/rating:viewany - allows the user to view aggregated ratings made on other people's items

moodle/rating:viewall - allows the user to see individual ratings

moodle/rating:rate - allows the user to make ratings on other people's items

====Handling of old permissions====

Pre-existing module-specific permissions will be extended to have matching names/behaviour with the new rating permissions.

*mod/data:rate - unchanged
*mod/data:viewrating - unchanged
*mod/data:viewanyrating - cloned from old mod/data:viewrating
*mod/data:viewallratings - cloned from old mod/data:viewrating
*mod/forum:rate - unchanged
*mod/forum:viewrating - unchanged
*mod/forum:viewanyrating - unchanged
*mod/forum:viewallratings - cloned from old mod/forum:viewanyrating
*mod/glossary:rate - unchanged
*mod/glossary:viewrating - unchanged
*mod/glossary:viewanyrating - cloned from old mod/glossary:viewrating
*mod/glossary:viewallratings - cloned from old mod/glossary:viewrating

===Module callbacks===

These allow modules to control how ratings behave.

====modname_rating_validate====

As of Moodle 2.0.3 modules must implement a function named '''modname_rating_validate''' to verify the validity of submitted ratings.

This function must return true if the rating is valid or throw an instance of rating_exception if the rating is invalid. Note: false is used to indicate that the module hasn't implemented this callback.

This example shows how this would work for the forum module
<code php>
function forum_rating_validate($params) {
if (!array_key_exists('itemid', $params) || !array_key_exists('context', $params) || !array_key_exists('rateduserid', $params)) {
throw new rating_exception('missingparameter');
}
return true;
}
</code>
The rating_exception argument is the name of a string in the error language file.

The $params argument contains:
* context - object the context in which the rated items exists [required]
* itemid - int the ID of the object being rated
* scaleid - int the scale from which the user can select a rating. Used for bounds checking. [required]
* rating - int the submitted rating
* rateduserid - int the id of the user whose items have been rated. NOT the user who submitted the ratings. 0 to update all. [required]
* aggregation - int the aggregation method to apply when calculating grades ie RATING_AGGREGATE_AVERAGE [required]

====modname_rating_permissions====
Modules must implement a function named '''modname_rating_permissions''' to control post and view permission. This is called prior to rendering a set of ratings. It is also called by rating/rate.php and rate/rate_ajax.php when they receive rating submissions.

Modules do not need to implement this. It's mostly provided for backward compatibility with modules that had complicated ratings related logic or for modules that use settings other than capabilities to control ratings behavior.

This function will return an array: array('view'=>true, 'viewany'=>true, 'viewall'=>true, 'rate'=>true)

This example shows how this would work for the forum module
<code php>
function forum_rating_permissions($context) {
return array('view'=>has_capability('mod/forum:viewrating',$context),
'viewany'=>has_capability('mod/forum:viewanyrating',$context),
'viewall'=>has_capability('mod/forum:viewallratings',$context),
'rate'=>has_capability('mod/forum:rate',$context));
}
</code>

==See also==

* MDL-21657 Implement Ratings 2.0

[[Category:Grades]]

Development:Blog 2.0

2021-07-14T13:24:10Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Work in progress}}{{Moodle 2.0}}

* '''PROJECT STATE: Coding'''
* '''MAIN TRACKER ISSUE''': MDL-19676 Blog 2.0 improvements
* '''DISCUSSION AND COMMENTS''': http://moodle.org/mod/forum/discuss.php?d=133348

== Description of improvements ==
=== Who can view blog entries? ===
Blog entries are either in draft mode (only the author can view it), or in public mode. In public mode, everyone on the entire site can view the blog entry.

Before 2.0 there was an attempt to restrict who can view certain blog entries, based on course enrolment and capabilities. However, after extensive discussion and feasibility testing it became clear that this could lead to serious performance and usability issues on large sites, and was turning the blog into something more akin to a forum. It was thus decided to make all blogs public. (See MDL-19676)

This simplification means that sites using the old BLOG_GROUP_LEVEL and BLOG_COURSE_LEVEL and values of $CFG->bloglevel have to perform an special upgrade which copies all the site's blog entries into a special "blog-type" forum in each course in which the blog entry's author is enrolled, then disables blogging at site level.

Capabilities:
*moodle/blog:view
*moodle/blog:viewdrafts

=== Associations ===
A blog entry can optionally be associated with a course. This makes it possible for a user to blog "about" that course. All blog entries associated in that way can be viewed on a page like blog/index.php?courseid=3. This type of filtering of blog entries does not take into account course enrolments.

Additionally, blog entries can be associated with an activity module.

This requires the creation of a new table, in which the associations are recorded.
Tracker issue: MDL-14408

Capabilities:
*moodle/blog:associatecourse
*moodle/blog:associatemodule

=== Improved navigation ===
Before 2.0, the navigation for any listing of blog entries was either "Site > User > Blogs" (for a user's blog entries) or "Site > Blogs" for the whole site's blog entries, optionally filtered by tag. With the new association features, we need a better way to display what type of blog listing we are looking at, based on the parameters passed to blog/index.php. The navigation should also reflect additional filters such as tag and search.

=== External blogs ===
A user can specify external blogs which publish an RSS/ATOM feed. This feed is then checked periodically through a cron task, and entries are copied into the user's blog in Moodle, as read-only entries.

This synchronisation checks if external entries have been modified or deleted since the last sync, and updates the Moodle entries accordingly.

These external blogs are a user preference, and two types of tags can be added to each of them: "Filter tags" and "Automatic tags":
*Filter tags are used to filter the external blog entries that get copied into Moodle. They must match the tags used by that external blog. An external entry will be selected if it has at least one of the filter tags. (Tags are called "categories" in RSS feeds)
*Automatic tags are automatically added to each blog entry copied into Moodle from an external blog that uses such tags.

This requires the creation of a new DB table.
Tracker issue: MDL-19683

Capabilities:
*moodle/blog:manageexternal

=== Search blog entries ===
It is now possible to search blog entries using a search box. The results maintain the current context, so that if you are viewing a list of blog entries for a particular user, entering a term in the search box will return only the blog entries for that user that match the search term. The search term also appears in the navigation breadcrumbs.

Tracker issue: MDL-19686

Capabilities:
*moodle/blog:search

=== Contextual blog menu ===
Previously, the "blog menu" block was the same on every page on which it appeared. In 2.0 it changes depending on which page you are. For example, if you are on course/view.php, it will include a link to blog entries associated with that course. Also, the link for adding a new entry will include the courseid, making the course association automatically pre-selected in the blog entry edit form.

Tracker issue: MDL-19687

=== File attachments ===
The [[Development:File_API|new file manager]] must be implemented to allow for multiple file attachments per blog entry.

Tracker issue: MDL-19744

=== Comments ===
The new [[Development:Comments_2.0|Comments API]] makes it possible for anyone having the correct capability to comment on blog entries.

Tracker issue: MDL-8776

=== New "Recent blog entries" block ===
This block can be configured to display the last N blog entries, filtered by context. For example, if you are viewing an assignment activity, this block would display the last N blog entries that are associated with that assignment.

Tracker issue: MDL-19688

== Potential problems and limitations ==

===Upgrade from "Users can only see blogs for people who share a course"===

This mode was always a slightly quirky and uncomfortable hack. It was mostly useful for sites with very distinct courses and users, such as those where each course consists of the employees from a separate company, and My Moodle was used to hide the companies from each other. However, for the general case, the main problem is that you see ALL blog entries from those people, not just ones that are about your courses.

This mode has no direct equivalent in Moodle 2.0 because we have resolved not to emulate "course-like" modes within a system that is at system level, and outside the courses. This helps understanding of the blog system, simplifies the implementation and improves performance.

However some people may be using that mode so we do need to provide an upgrade path for them.

Informationally, the idea of just seeing all the blogs from people who are in your course is the same as a course forum.

So a possible upgrade would be to do this:
If the mode is set to "Users can only see blogs for people who share a course" then
Set the new mode to "Users can only see their own blog"
Foreach user who has a blog
Foreach course that user is enrolled in
If a "Course blogs (recovered)" forum doesn't exist yet in the course (section 0) then create one
Foreach blog entry that the user created
Create a new discussion from the blog post with the same dates, attachments etc

This way no data is lost. The teachers can choose to delete the whole forum if they choose to. The original blog entries should not be touched.

== DB Structure ==
2 new tables need to be added: blog_external and blog_association

=== blog_external ===

{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this external blog.
|-
| userid
| int(10)
|
| The owner of the external blog
|-
| name
| char(255)
|
| A descriptive name for the external blog. Automatically fetched during initial import, can be overridden.
|-
| description
| text(small)
|
| A long description of the external blog. Automatically fetched during initial import, can be overridden.
|-
| url
| text(small)
|
| The URL to the external blog (e.g. http://moodle.org/rss.xml)
|-
| failedlastsync
| int(1)
|
| Whether or not the last synchronisation failed
|-
| timemodified
| int(10)
|
|
|-
| timefetched
| int(10)
|
| The last time the entries from this external blog were fetched by Moodle.
|}

=== blog_association ===

{| class="wikitable"
|-
! Field
! Type
! Default
! Info
|-
| id
| int(10)
| auto-incrementing
| The unique ID for this blog entry<->contextid association.
|-
| contextid
| int(10)
|
| The context id defined in context table - identifies the instance of the course or plugin associated with the blog entry.
|-
| blogid
| int(10)
|
| The id of the blog entry (from the post table) being associated with a course or module instance
|}

== Upgrade process ==
The only task required by the upgrade process is to install the new DB tables.

== See also ==
*[[Development:Blogs|Early wishlist]]
*[[Student_projects/Blog_improvements|2008 GSoC project addressing some of these improvements]]

[[Category:Blog]]

Development:Languages/AMOS

2021-07-14T13:24:09Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Infobox Project
|name = Automated manipulation of strings
|state = Production
|tracker = MDL-18797
|discussion = [http://moodle.org/mod/forum/discuss.php?d=118707#p542197]
|assignee = [[User:David Mudrak|David Mudrak]]
}}
{{Moodle 2.0}}

'''AMOS stands for Automated Manipulation of Strings. AMOS is a central repository of Moodle strings and their history. It tracks the addition of English strings into Moodle code, gathers translations, handles common translation tasks and generates language packages to be deployed on Moodle servers.'''

The name was chosen in honour of [http://en.wikipedia.org/wiki/John_Amos_Comenius John Amos Comenius], the author of ''Janua linguarum reserata'' (Gate to Languages Unlocked), who may be considered the father of modern education.

== AMOS design ==

This part of the document was the original specification used for development.

=== Overall picture ===

[[Image:lang20amosflow.png]]

# Developers add new string by adding them into appropriate English $strings array definition file (eg /mod/workshop/lang/en/workshop.php). This file is committed into Moodle main CVS repository as a part of the code.
# CVS repository is mirrored automatically on the fly in a git repository. This git repository is used for further processing because parsing the strings file and tracking their history is much simpler in this system. The whole history is present in the git clone so there is no need to ask CVS server for anything once it is fetched.
# Git repository is regularly checked for any changes in string definition files. Once a modification is detected, the file is parsed and any addition, modification or removal of a string is recorded in an English strings database, together with a meta-information about the author of the change, timestamp, branch, commit identification (git commit hash) etc.
# Translators use the strings definition stored in the English strings database as a reference for their translation. Therefore the information about the origin (the branch and the revision) of the translated English string can be stored as meta-info together with the translation. Every translated string is linked with a certain revision of the English source so we can easily find strings there were modified in English to be re-checked etc.
# So called translation stage (or cache) is used during the translation. This is similar to the session cache when working with [[XMLDB]]. Once the translator is happy with the work, she/he commits (submits) the translation into the database of the translated strings.
# Non-English strings database contains the history of the translation of all Moodle strings in all supported languages. This database is used as a source to generate the up-to-date language package in various formats (ZIP to be deployed at the servers, XML to be used by an external translation tools etc).
# Moodle site administrators update their installed language packs by downloading the ZIP files generated from the database (or, in the future, they can fetch the pack in other format)

=== AMOS processes ===

[[Image:lang20amosflow2.png]]

;Tracking CVS commits : run as a cron job. Looks for new/modified/removed strings in Moodle source code (core and contrib) and registers these changes in AMOS database.
;Uploading strings : both English and translated strings may be registered from uploaded files. This way, 3rd modules not tracked by AMOS automatically (because they are not in our contrib) can be processed in AMOS.
;Translating strings via web : AMOS provides an interface for translating stored strings (MDL-21691).
;Staging : Strings from various sources end in a [http://en.wikipedia.org/wiki/Staging_(data) staging area]. They are stored here temporarily before they are committed into the main strings table.
;Committing : A set of strings in the stage is committed into the main strings table.

Thanks to this design, we have a single interface to get data from stage into the main strings repository. For every supported format/way to get strings, just a class implementing 'stageable' interface is needed to convert the input format into the staging area.

Hierarchy of classes is expected to be available for input processing. For example, the process that tracks commits history in CVS prepares a PHP file with the checkout. So we have a class that is able to convert array $string[] defined in PHP file into staging area. Once we have such class, it can be used to process PHP files uploaded by developers/translators, too.

=== Implementation plan ===

The implementation proposal evolved from the idea by Petr Skoda [http://moodle.org/mod/forum/discuss.php?d=118707#p542197 discussed at moodle.org]. The key point is that translators do not have direct access to the source code repository (CVS) any more. There is a central tool (known as AMOS nowadays) that looks after proper branching and keeping history of the language packs. The current proposal follows.

# There a separate Moodle 2.0 site at http://lang.moodle.org MNet'ed with http://moodle.org. This site is intended for our developers, translators and other community members interested in the translation process. Current Languages forum at Using Moodle can be eventually moved into this new languages portal.
# AMOS is implemented as a local plugin /local/amos installed at http://lang.moodle.org. Because this is the only Moodle site with this plugin, using /local plugin mechanism is a natural way to implement, develop and maintain it.
# There is a course "Moodle Translation" in this portal containing (among other useful things) a clear link to the /local/amos/view.php page.
# During Moodle 2.0 beta period, translator use AMOS portal to prepare the translations of the new Moodle release.
# AMOS installation at http://lang.moodle.org uses its own git clone of our official git mirror to have access to the English strings. Keeping the git mirror up-to-date and synced is a prerequisition for the proper AMOS functionality.

=== Use cases ===

# ''Developers'' write the code and commits it into CVS. They can create or modify English strings as needed in the current way of direct modification of the strings definition file.
# ''Translators'' come to http://lang.moodle.org to translate Moodle. No other way is possible yet.
## translators can choose the Moodle version (1.8, 1.9 or 2.0) to translate
## translators can display the list of missing strings to translate
## translators can display the list of English strings that were modified since their last translation so they should be re-checked
## translators can display the history of string wording, authors of the change, commit messages explaining the change
## other useful tools and filters are available, like displaying all strings containing a given phrase etc. See MDL-18797 for details
## after providing new or modified translations, translators "commit" their changes through the web interface, providing a commit message
# ''Administrators'' can download language packages as ZIP files from http://download.moodle.org or let them update automatically from the Moodle
## packages are regenerated automatically as they are at the moment, with the only difference that the database and not CVS is used as their source
# ''Contributors'' [must think about this yet] - their plugins in CONTRIB can be mirrored into git (one day this will happend anyway ;-)) and then AMOS can process them easily. Or we could add a feature that the contributor can upload the file with English strings definition manually and "register" the strings this way.

== Database structure ==

The core of the whole AMOS system is a single table containing the history of all changes of all strings from all components in all languages. This one is called amos_repository. All other operations, like committing a translation, getting the current snapshot etc., are based on this table. After an initial import of CVS history, the table contains around 3.6 millions of records.

There is yet another table where the permissions to translate a language are stored, which is not so important and is trivial (therefore not documented here).

=== amos_repository ===
Contains all Moodle strings and their history

{| class="wikitable"
! Field
! Type
! Description

|-
| id
| int (10) unsigned not null seq
|

|-
| branch
| int (10) unsigned not null
| The code of the branch this string is valid for

|-
| lang
| char (20) not null
| The code of the language this string belongs to. Like en, cs or es

|-
| component
| char (255) not null
| The name of the component this string belongs to. Like moodle or workshopform_accumulative

|-
| stringid
| char (255) not null
| The code of the string

|-
| text
| text (big) not null
| The localized string text

|-
| timemodified
| int (10) unsigned not null
| The timestamp of the commit

|-
| commitmsg
| text (big)
| Commit message

|-
| commithash
| char (40)
| The git commit hash that introduced this string

|-
| source
| char (255)
| The source of this string - git, email etc.

|-
| deleted
| int (2) unsigned default 0
| Is the string deleted? If not, it will be generated into the lang packs

|-
| userid
| int (10) unsigned
| If the author is known in the local user table, store their id here

|-
| userinfo
| char (255)
| Helps to identify the author of the change, for example a name from CVS commit

|}
==== Keys ====

{| class="wikitable"
! Name
! Type
! Field(s)
! Reference

|-
| primary
| primary
| id
|

|-
| fk_user
| foreign
| userid
| user (id)

|}
==== Indexes ====

{| class="wikitable"
! Name
! Type
! Field(s)
! Description

|-
| ix_snapshot
| Not unique
| component, lang, branch
| Optimised for getting a snapshot of all current strings in one component

|-
| ix_lang
| Not unique
| lang
| For getting a list of all known components. In some cases, we need to filter English records only

|-
| ix_timemodified
| Not unique
| timemodified
| This index allows to search for the recent records in the log output

|}

== Features ==

=== Tracking the changes in the English strings ===

Implemented in: /local/amos/cli/parse-core.php

AMOS uses its own git clone of Moodle repository. It runs 'git whatchanged' to see what files were affected by every single commit ever. Once it detects a change in a valid English string file, it checks out that revision of the file and compares its content with the current snapshot of the strings database. New record is added into the strings table for every new, modified or removed string in the checked out file. The commit hash of the last fully processed commit is stored in $CFG->dataroot/amos/var/MOODLE_xx.startat so that next time AMOS analyzes just new commits.

=== AMOS script ===

AMOS script allows us to propagate changes in the English language pack into other languages.

Sometimes we want to reorganize the English language pack - for example split a component into subcomponents (as happened with auth.php), rename string identifiers, fork a string according the meaning (e.g. 'fullname' may be different when talking about a human and about a course) etc. Such a change can be easily done in English by direct editing and committing the lang/en/*.php files. But the translation would get lost and our poor translators would have to translate such strings again.

There is a way how to instruct AMOS to propagate a change in the English lang pack into all other languages at the given branch. We call that AMOS script (or amosbler for the syntax similarity with the assembly language - assembler). Such a script can be uploaded or pasted into a page at AMOS portal and it will just follow the instructions provided. Or - which is more interesting - such a script can be put directly into the commit message of the commit that does the change in the English language pack. In that case, AMOS will automatically run the script right after it process the commit.

Here is an example of a script that instruct AMOS to process a set of bulk operations over language packages:

AMOS BEGIN
MOV [description,mod_workshop],[intro,mod_workshop]
CPY [submission,mod_assignment],[submission,mod_workshop]
HLP forum/forumtype.html,[forumtype_hlp,mod_forum]
AMOS END

In this example, there are three instuctions to be done. The line with MOV ('move') command instructs AMOS to rename the string 'description' defined in workshop to the new identifier 'intro'. The second command CPY ('copy') orders to create new string in the workshop module with the identifier 'submission' and the value of that string shall be taken from the $string['submission'] in the module assignment. If such string already exists in any language, CPY will not replace it. The third command is used for migrating legacy HTML help files into ordinary strings. It tells AMOS to add new $string['forumtype_hlp'] in every language, using the content of the help file 'forum/forumtype.html' as the initial value.

The script syntax is defined as follows. Note that amosbler keywords are case sensitive so must be upper-case. In pseudo-regexp, the valid AMOS script is defined as:

^[:blank:]*AMOS BEGIN[:blank:]*$
^[:blank:]*[A-Z]{3}[:blank:]+(param1),[:blank:]*(param2), ...,[:blank:]*(paramn)[:blank:]$
...
^[:blank:]*AMOS END[:blank:]*$

In human language, this roughly means: the script is a block of lines starting with 'AMOS BEGIN' or 'AMOS START' and ending with 'AMOS END' lines. Every instruction is on its own line. Instruction has its name (three capital letters like MOV, CPY, HLP, RPL, SMS or GRR) followed by comma-separated parameters.

'''Beware:''' Every string is referenced as [stringid,component] '''but the component is different from what we use in get_string()'''. All components use fully normalized plugintype_pluginname syntax (see normalize_component() function in moodlelib). If plugintype === core and pluginname is empty (component 'core'), the strings are stored in moodle.php.

{| class="wikitable"
! String identification in get_string()
! String identification in AMOS

|-
| get_string('edit', 'moodle')
| [edit,core]

|-
| get_string('submit', 'assignment')
| [submit,mod_assignment]

|-
| get_string('grade_help', 'grades')
| [grade_help,core_grades]

|-
| get_string('send', 'message')
| [send,core_message]

|-
| get_string('hello', 'block_greetings')
| [hello,block_greetings]

|}

Currently planned/implemented AMOS script instructions are:

; MOV [source],[target] : Move the string. If the source stringid is already defined in the target component, it is not replaced.
; CPY [source],[target] : Copy the string. Works as MOV but the source string is not touched.
; HLP component/helpfile.html,[string] : Convert legacy HTML help file to the string
; REM text : Allows to put a remark (comment), for example to describe a required operation that can't be achieved by current instruction set.

Ideas for other future instructions: RPL for replace (forced MOV), SMS for sending a message, GRR for something unknown yet but such instruction just must be there ;-)

Note there are no instructions DEL or ADD. AMOS automatically recognized new strings as well as their removal from the commit diffs.

'''Summary of using AMOS script in commit messages:'''

# The commit must modify some string file, AMOS would ignore the commit completely otherwise
# The script must be properly formatted as block of lines
# The strings must be identified in normalized syntax - the main difference is using core for moodle.php and core_* prefix for components in lang/en/*.php
# Note that it may take up to an hour that your CVS commit is mirrored into git and then processed by AMOS

=== Generating installer files ===

Implemented, not automated yet

See cli/export-installer.php.

== Deployment settings ==

# crontab -l
0,30 01-23 * * * /usr/local/bin/amos-update > /tmp/amos-update.log
0 0 * * * /usr/bin/php /var/www/htdocs/moodle-amos/local/amos/cli/rev-clean.php --full > /tmp/amos-full-rev-clean.log

#!/bin/bash

# /usr/local/bin/amos-update
# Updates AMOS working repositories and registers changes
# To be run regularly after git sync

AMOSCLIDIR=/var/www/htdocs/moodle-amos/local/amos/cli
AMOSREPOCORE=/var/www/data/moodle-amos/amos/repos/moodle
AMOSREPOLANG=/var/www/data/moodle-amos/amos/repos/moodle-lang
PHP=/usr/bin/php

cd $AMOSREPOCORE && /usr/local/bin/git pull --quiet
cd $AMOSREPOLANG && /usr/local/bin/git pull --quiet

$PHP $AMOSCLIDIR/parse-core.php && $PHP $AMOSCLIDIR/parse-lang.php && $PHP $AMOSCLIDIR/rev-clean.php

[[Category:Language]]

TinyMCE editor

2021-07-14T13:24:08Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Editing text}}
The TinyMCE text editor is an editor plugin in Moodle which can be enabled, disabled or set as default from ''Administration > Site administration > Plugins > Text editors > Manage editors''.

Users may also select the TinyMCE editor (in preference to the default editor Atto) from the user menu top right>''Preferences>Editor preferences''

==Collapsing and expanding the editor==

The TinyMCE editor first appears with just one row of buttons. Clicking the icon top left will expand it to three rows.

{|
|[[File:26tinymce1.png|250px|thumb|Collapsed view]]
|[[File:26tinymce2.png|250px|thumb|Expanded view]]
|}

==Toolbar buttons==
For those who are not familiar with the tool bar, here are the buttons as grouped in their rows. Remember that the site administrator can edit or provide additional buttons.

Row 1
{|
|[[File:26tinymcerow1.png|400px|thumb]]
|}

{| class="wikitable"
|-
|-
| 1:Expand
| 2.Formatting
| 3.Bold
| 4.Italic
|-
| 5.Bulleted list
| 6.Numbered list
| 7.Add link
| 8.Unlink
|-
| 9.Stop auto linking
| 10.Add image
| 11.Add emoticon
| 12.Add media
|-
| 13.Manage embedded files
|
|
|
|}
Row 2

{|
|[[File:26tinymcerow2.png|400px|thumb]]
|}

{| class="wikitable"
|-
|-
| 1:Undo
| 2.Redo
| 3.Underline
| 4.Strikethrough
|-
| 5.Subscript
| 6.Superscript
| 7.Align left
| 8.Align centre
|-
| 9.Align right
| 10.Decrease indent
| 11.Increase indent
| 12.Text colour
|-
| 13.Background colour
| 14.Left to Right
| 15.Right to Left
|
|-

|}
Row 3

{|
|[[File:26tinymcerow3.png|400px|thumb]]
|}

{| class="wikitable"
|-
|-
| 1:Font family
| 2.Font size
| 3.Edit HTML
| 4.Find
|-
| 5.Find/replace
| 6.Insert non-breaking space
| 7.Insert special character
| 8.Insert table
|-
| 9.Clean up messy code
| 10.Remove formatting
| 11.Paste as plain text
| 12.Paste from MS Word

|-
| 13.Toggle full screen
|-

|}

===Colour pickers===
*[[Image:26colourpickers.png]]
There are four levels of selecting a font or background colour,
*A quick pick 5x8 matrix of colours
*"More colours" that links to Picker, Pallet and Named tabs
<gallery>
Image:HTML_editor_color_selector_basic_1.png|A quick pick 5x8 matrix of colors
Image:HTML_editor_color_selector_more_picker_1.png|A rainbow color picker tab
Image:HTML_editor_color_selector_more_pallet_1.png|A Pallet tab with a 18x12 matrix of colors
Image:HTML_editor_color_selector_more_named_1.png|A Named tab with custom pallets
</gallery>

====Insert table====
<gallery widths="300px">
Image:HTMLeditor_Insert_Table_general_1.png|General tab
Image:HTMLeditor_Insert_Table_advanced_1.png|Advanced tab
</gallery>

'''To add borders to a table'''

Cell borders are crucial for helping readers to follow the rows across the screen. If they aren’t showing already you can add them as follows:

#In the Wiki page containing your table, click its Edit tab
#Carefully select all the cells of the table
#Then right click (Macs: Command+click or Ctrl+Click) over any part of your selection to get a context menu; from it select Cell > Table Cell Properties; the cell properties dialog box then loads.
#Click on its Advanced tab, set Border Color to black (for instance), then click Apply, and then click Update.
#Click Save; the Wiki page containing your table will then load displaying its borders.

===TinyMCE editor settings===

The TinyMCE HTML editor has its own settings page ''Administration > Site administration > Plugins > Text editors > TinyMCE HTML editor > General settings'' with the following options:

====Plugins====
*Buttons for equations, emoticons,images, media, automatic linking, and legacy spell-checking may be enabled, disabled or uninstall here by clicking on their eye.
*Additionally the equation, emoticon and spell check buttons have links to their Settings screens.

[[File:26tinymceplugins.png |thumb|none|upright=2.0|alt="The TinyMCE editor plugins screen" | The TinyMCE editor plugins screen]]

=====Manage embedded files=====

This plugin allows users to add, delete or override files embedded in the current text area, for example in a label or topic summary. (It complements the [[Embedded files repository]])

{|
|[[File:26embeddedfiles1.png|thumb|The Manage files button]]
|
|[[File:26embeddefiles2.png|thumb|Managing embedded files from within TinyMCE]]
|}

=====Insert equation=====

Accessed from ''Administration>Site administration > Plugins > Text editors > TinyMCE HTML editor > Edit equation'', this allows you to enable or disable the TeX filter in the editor context and thereby display the Dragmath button. If you have a global custom TeX filter, then disable this setting.

=====Insert emoticon=====
Accessed from ''Administration > Site administration > Plugins > Text editors > TinyMCE HTML editor > Insert emoticon'', this allows you to enable or disable the emoticon filter in the editor context and thereby display the emoticon button.

===== Legacy spell checker=====
The legacy spell checker is visible in IE9 and lower only, but not in other browsers. If you want to disable it and and rely on browser spell checker functionality instead, you can do this by disabling the ''legacy spellchecker'' plugin by clicking its eye in ''Administration > Site administration > Plugins > Text editors > TinyMCE HTML editor > General settings''

To spell-check via your browser, type your word (which if incorrectly spelt will have red lines under it) and press right click + CTRL
{|
|[[File:Browserspellcheck.png|thumb|Right-click+CTRL for browser spellcheck]]
|}

'''NOTE:'''
While the default spell engine is Google spell which can be changed in ''Administration>Site administration>Plugins>Text editors>TinyMCE HTML editor'', this is no longer supported by Google and will not work. (Note that it is only visible in IE9 and lower) It is due to be removed. See MDL-38867. In browser spell check is recommended.

If PSpell is selected then aspell 0.50 or later must be installed on your server and the path to aspell set in Administration > Site administration > Server > System Paths.

You can select a different spell engine from ''Administration> Site administration > Plugins > Text editors > TinyMCE HTML editor>Check spelling''.

{|
|[[File:Spellengine.png|thumb|Choosing a different spell engine]]
|}
According to: http://php.net/manual/en/book.pspell.php

"As of php 5.3. Pspell is no longer supported/bundled. Instead you can use the enchant which is bundled by default in 5.3."

If PSpell is selected then aspell 0.50 or later must be installed on your server and the path to aspell set in Administration > Site administration > Server > System Paths.

===Customising the editor toolbar===

An administrator can remove or add buttons to the TinyMCE editor toolbar by altering the Editor toolbar box in '' Administration > Site administration > Plugins > Text editors > TinyMCE HTML editor > General settings'' as demonstrated in the screencast [http://youtu.be/vTW1DImro9c Customise the text editor in 2.4].

{|
| [[File:editortoolbar.png|thumb|The Editor toolbar box]]
|[[File:horizontalrule.png|thumb|Example of toolbar with added horizontal rule button]]

|}

====Available fonts list====

In addition to the default fonts, a site administrator can add extra fonts by typing their name and string in the box in ''Administration > Site administration > Plugins > Text editors > TinyMCE HTML editor > General settings'' as demonstrated in the screencast [http://youtu.be/udP7Bnur30Y How to add extra fonts].

{|
|[[File:comicsans.png|thumb|Example of custom font]]
|}

====Custom configuration====

A setting in ''Administration>Site administration>Plugins>Text editors>TinyMCE HTML editor>General settings'' provides a box in which an administrator can apply custom formats. See MDL-37186 for more details with examples, and see also the [http://www.tinymce.com/wiki.php/Configuration:formats TinyMCE configuration page]

{|
|[[File:bottomtoolbar.png|thumb| Example 1:Toolbar at the bottom]]
|[[File:customstyles.png|thumb| Example 2: Custom styles]]
|}

*Example: Moving the toolbar to the bottom:

Add the following:
{"theme_advanced_toolbar_location" : "bottom"}

*Example: Adding your own custom styles.
(This might be useful for example if you want a "house style" for important notes, key points or similar)
In the editor toolbar, enter "styleselect" and then in the custom box add the following code, changing it to suit your purposes:
{"style_formats" : [
{"title" : "Bold text", "inline" : "b"},
{"title" : "Red text", "inline" : "span", "styles" : {"color" : "#ff0000"}},
{"title" : "Red header", "block" : "h1", "styles" : {"color" : "#ff0000"}} ]}

The following will let you use bootstrap CSS classes if you use a bootstrap based theme:

{"style_formats" : [
{"title" : "Well", "block" : "div", "classes" : "well"},
{"title" : "Label", "inline" : "span", "classes" : "label"},
{"title" : "Label - success", "inline" : "span", "classes" : "label label-success"},
{"title" : "Label - warning", "inline" : "span", "classes" : "label label-warning"},
{"title" : "Label - important", "inline" : "span", "classes" : "label label-important"},
{"title" : "Label - info", "inline" : "span", "classes" : "label label-info"},
{"title" : "Label - inverse", "inline" : "span", "classes" : "label label-inverse"},
{"title" : "Button", "inline" : "a", "classes" : "btn btn"},
{"title" : "Button - primary", "inline" : "a", "classes" : "btn btn-primary"},
{"title" : "Button - info", "inline" : "a", "classes" : "btn btn-info"},
{"title" : "Button - success", "inline" : "a", "classes" : "btn btn-success"},
{"title" : "Button - warning", "inline" : "a", "classes" : "btn btn-warning"},
{"title" : "Button - danger", "inline" : "a", "classes" : "btn btn-danger"},
{"title" : "Button - inverse", "inline" : "a", "classes" : "btn btn-inverse"}
]}

*Example: Enabling copy of rich content with styles from MS Word (tm) and paste into TineMCE without removing important styles:

{"paste_retain_style_properties" : "margin, padding, width, height, font-size,
font-weight, font-family, color, text-align, ul, ol, li,
text-decoration, border, background, float, display"}

==Speed of TinyMCE in Firefox and Chrome==
Some users have complained about the unreasonably slow loading of TinyMCE; for example, https://moodle.org/mod/forum/discuss.php?d=232089 and https://moodle.org/mod/forum/discuss.php?d=223125. [https://moodle.org/mod/forum/discuss.php?d=262235 Apparently,] TinyMCE takes longer to load in Firefox (10-20 seconds) than in Chrome (a couple of seconds).

To speed up TinyMCE you can try disabling ALL the plugins in the TinyMCE editor settings from your admin account: <moodle site address>/admin/settings.php?section=editorsettingstinymce . Then the editor loaded quickly. This has taken out a couple of minor functions, such as inserting emoticons, but loading speed is far more important for some users than the ability to insert emoticons.

===Screencasts===
[http://www.youtube.com/watch?v=1m2xkm2EyXA&feature=share&list=SPxcO_MFWQBDe8RRnGjoUDqbcm9PSlIoWn&index=4 TinyMCE text editor improvements.]

==TinyMCE additional plugins==
In Moodle 2.4 and later, the TinyMCE editor can be extended and replaced by new plugins available in the [https://moodle.org/plugins/browse.php?list=category&id=45 Moodle plugins database]. Some of these plugins are:

* [[Cloze editor for TinyMCE]] for easily adding [[Embedded Answers (Cloze) question type]].
* [https://moodle.org/plugins/view.php?plugin=tinymce_wordcount Word count] prints a word count in the bottom right-hand corner of your TinyMCE editor which updates as you type.
* [[TinyMCE Mathslate]] is a [[Mathematics]] editor that does not depend on Java.
* [https://moodle.org/plugins/view.php?plugin=tinymce_youtube YouTube Anywhere] enables direct recording and uploading into YouTube from the TinyMCE HTML editor.

[[es:Editor TinyMCE]]
[[de:TinyMCE-Editor]]
[[fr:Éditeur TinyMCE]]

Editing Questionnaire questions

2021-07-14T13:24:07Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Questionnaire}}

==Editing questions==
* On the Questionnaire '''Editing Questions''' page is displayed a drop-down list of the question types available and a list of the questions already created for the current questionnaire instance (if any).
* Using the standard Moodle icons you can change the order of the questions in the questionnaire, edit or delete questions.

==Common options==
===Question Name===

====Questionnaires '''not''' using the Conditional Branching or the Personality Test features====

You can ''optionally'' enter a '''Question Name''' for each question.

If your questionnaire does not use the "Conditional Branching" or the "Personality Test" feature, the '''Question Name''' is only used when you export responses to CSV/Excel format. If you never export to CSV, then you needn't worry about Question names. If you plan to regularly export your questionnaire data to CSV, then you have a choice of two options for question naming.

=====Option 1: significant names=====

In the '''Question Name ''' box, enter ''meaningful'', ''short'' and '''''different''''' question names for all of the questions within one questionnaire. In the CSV export file, all those question names will be prefixed with the question's actual number (= position) in the quiz. Examples:

{| border="1"
! scope="col" | question number (position) in the questionnaire
! scope="col" | question name entered by teacher
! scope="col" | field header in csv export
|-
|
<div style="text-align: center">5</div>
| favorite colors
| Q05_favorite colors
|-
|
<div style="text-align: center">6</div>
| why_use_Moodle
| Q06_why_use_moodle
|-
|
<div style="text-align: center">7</div>
|
user-friendliness

'' (rate question with 3 possible answers: Moodle, WebCT and Blackboard) ''
|
Q07_user-friendliness->Moodle<br /> Q07_user-friendliness->WebCT<br /> Q07_user-friendliness->Blackboard
|}

=====Option 2: leave the Question Name boxes blank=====

For each un-named question, CSV export will automatically generate a question name. This is required for table header fields in the CSV and subsequent Excel tables or any statistics package you might be using. The question name generated will be based on the question number in the actual Quiz (excluding ''Section Text'' pseudo-questions, of course) e.g. Q01, Q02, ... Q99. For questions with multiple answers, such as rate-type or Likert type questions, a sub-question number will be generated (Q02_1, Q02_2, Q02_3, etc.). This type of "short-name" naming scheme is advisable for exporting your data to a statistics software. Of course, it's up to you to have your own system for remembering which abbreviated question name corresponds to which question in your questionnaire!

{| width="100%" border="1"
! style="width: 33%" scope="col" | question number (position) in the questionnaire
! style="width: 33%" scope="col" | question name entered by teacher
! style="width: 33%" scope="col" | field header in csv export
|-
|
<div style="text-align: center">5</div>
| style="background-color: #CCCCCC" |
| Q05
|-
|
<div style="text-align: center">6</div>
| style="background-color: #CCCCCC" |
| Q06
|-
|
<div style="text-align: center">7</div>
| style="background-color: #CCCCCC" |
|
Q07_1<br /> Q07_2<br /> Q07_3
|}

It is quite possible (but maybe not advisable) to mix the two systems, and have within one questionnaire both named and un-named questions.

====Questionnaires using the Conditional Branching feature====

If you need a question to be used as the "parent" of one or more subsequent questions in your questionnaire, then you '''must''' name that "parent question". Only those (radio buttons, dropdown list or yes/no) questions with a ''name'' will appear in the Parent question dropdown list when adding a new question, as shown on the following screenshots.

[[Image:05-08-2013 15-26-11.jpg]]

[[Image:05-08-2013 15-34-55.jpg]]

For more information, see [[Questionnaire_Conditional_branching|Conditional branching]].

===Response Required===
If you select '''''Yes''''', response to this question will be required, i.e. the respondent will not be able to submit the questionnaire until this question has been answered. If the respondent tries to submit a questionnaire with unanswered required questions (or, in the case of a questionnaire with more than one section, to go to the next page), a warning message will be displayed with a list of all the missing ''required ''questions in the questionnaire (or on the actual page).

Default.- '''''No'''''.

'''Note'''.- When you create new questions in sequence (one after the other), this parameter is carried over to subsequent questions. E.g. if you create question #1 with '''Response Required''' = '''''Yes''''', then the '''Response Required''' parameter will be pre-set to '''''Yes''''' for question #2, etc. You can of course change this parameter at any time.

In the ''Manage Questions'' section of the Questions editing page, once a question has been created, you can use the green and red dots to switch its Required state, as a shortcut alternative of editing the question.

[[Image:05-08-2013 15-49-48.jpg|300px]]

===Parent Question===

See [[Questionnaire_Conditional_branching|Conditional branching]]

===Question Text===
Enter your question text in this box. The HTML editor is available, which means that you can display not only formatted text but also images or other media in a questionnaire's questions text.

==Question Types==

Select the type of question from the drop-down list and click on the '''Add selected question type''' button.

===---Page Break---===

Use this to insert page breaks in longish questionnaires. Note that if a page contains questions with required response the respondent will not be allowed to navigate to the next page unless those required responses have been given.

If your questionnaire uses the Conditional branching feature, then page breaks will be ''automatically'' inserted when you add "parent" or "child" questions. Page breaks which are needed to ensure a correct "Conditional branching" flow cannot be moved or deleted. Their Move and Delete icons are disabled.

[[Image:05-08-2013 15-58-09.jpg|300px]]

===Check Boxes===
Check boxes allow the user to select multiple answers from a list of options.

==== Question editing interface ====

[[Image:05-08-2013 14-58-42.jpg|400px]]

==== Options ====

{| style="width: 100%" border="1" cellpadding="5"
! style="width: 50%" scope="col" | Editing Mode
! style="width: 50%" scope="col" | Questionnaire View
|-
|
{| style="width: 300"
| colspan="2" valign="top" | Question text: What are your favorite hobbies?

Possible answers:
|-
| style="border: #666666 thin solid" |
Watching TV<br /> Dancing <br /> Computing<br /> !other=Another hobby:
|}
|
[[Image:05-08-2013 13-29-49.jpg]]
|}

You may enter <tt>“!other”</tt> on a line to create an '''''optional''''' ''fill in the blank'' option. An<tt><nowiki>!other</nowiki></tt> box defaults to using the prompt ''Other: '', (or the equivalent translation for ''Other'' in the current language being used). You may change this default prompt by using the format: <tt>“!other=''prompt text”''</tt> as shown in the example above.

'''Notes.-'''

# At the moment the length of the ''fill in the blank'' input text box is set to 25 characters and is not customizable through the online interface.
# You may provide more than one <tt><nowiki>!other</nowiki></tt> ''fill in the blank'' option for a Check Boxes question, but this might cause problems so it is ''not recommended''.
# When a respondent answers a''' Check Boxes''' question which has been created as '''Required''', and the '''Min. forced responses '''and''' Max. forced responses''' parameters have been used, then a warning message will be displayed if respondent does not check the required number of boxes.
# Note that, if the <tt><nowiki>!other</nowiki></tt> ''fill in the blank'' option has been created, then if it is checked by the respondent, it will count in the total of minimum/maximum required check boxes.
# If a respondent checks a ''fill in the blank'' option '''check box''' and leaves the text field empty, ''that box will be unchecked'' (upon navigating to the next page or upon submitting the questionnaire).
# If a respondent has cheked ''a fill in the blank'' option '''check box''' and has filled in the text field, and later on changes his mind and unckecks that box, the ''fill in the blank'' text field will be automatically emptied (cool, ain't it?).

===Date===

''Use the day/month/year format, e.g. for March 14th, 1945: '''14/3/1945'''''

Use this question type if you expect the response to be a correctly formatted date. The format will depend upon the language currently being used by the questionnaire respondent. For example 4/21/2007 (US); 21/4/2007 (UK); 21-4-2007 (France); etc. An example will be displayed in the questionnaire. If an "impossible" or wrongly formatted date is entered, it will either be re-written or reformatted correctly (if possible) or an error message will be displayed to the respondent. In order for dates to be correctly exported to spreadsheets such as Excel, respondent must enter ''a date in the 1902 to 2037 range''. If a date outside this range is expected from respondents, then use the '''Text Box''' question type instead. The date question type will accept dates consisting only of a month plus a year (e.g. 12/2008 for december 2008) or only a year (e.g. 2008). However, for spreadsheet processing compatibility, such incomplete dates will be automatically transformed to complete dd/mm/yy dates, e.g. 12/2008 -> '''01/'''12/2008 and 2008 -> '''01/01/'''2008. You may have to explain this pecularity to your questionnaire users beforehand.

===Dropdown Box===

There is no real advantage to using the '''Dropdown Box''' over using the '''Radio Buttons''' except perhaps for longish lists of options, to save screen space.

===Essay Box===
====Question editing interface====
[[Image:2014-01-24_15-37-29.jpg|400px]]

====Settings====
This question will display a plain text box with '''x''' ''Textarea columns'' (or area ''width'') and '''y''' ''Textarea rows'' (number of text ''lines'').

If you leave both x and y to their default '''0''' value (or if you set it to '''0'''), then moodle's '''HTML editor''' will be displayed with standard height and width (if available in the course/user context & user profile).

===Label===

This is not a question but a (short) text which will be displayed to introduce a series of questions.

===Numeric===

Use this question type if you expect the response to be a correctly formatted number. By using the '''Max. digits allowed '''and '''Nb of decimal digits '''parameters you can specify the length and number of decimal places required. Use '''Max. digits allowed''' to set a limit to the number of characters entered for a Numeric question. Note that the decimal point also counts as one character! Use '''Nb of decimal digits''' to specify the format of the Average value counted and displayed at the Questionnaire Report page.

Examples:

{| class="wikitable"
|-
!
! Max. digits allowed
! Nb of decimal digits
! Response entered
! Average displayed
|-
| Example 1
| 6
| 2
| 12
| 12.00
|-
| Example 2
| 6
| 2
| 12.569
| 12.57
|-
| Example 3
| 8
| 1
| 12.57898
| 12.6
|}

=== Radio Buttons ===
====Question editing interface====
[[Image:05-08-2013 15-03-17.jpg|400px]]

====Radio buttons Alignment====
[[Image:05-08-2013 13-35-04.jpg]]

====Possible answers====
You must fill in one answer per line in the '''Possible answers''' box.

Examples:

{| border="1" cellpadding="5"
! style="width: 250" scope="col" valign="top" | Editing Mode
! style="width: 243" scope="col" valign="top" | Questionnaire View
! style="width: 434" scope="col" valign="top" | (optional horizontal display)
|-
| valign="top" |
'' 1.Possible answers''<nowiki>: </nowiki>

Red<br /> Blue<br /> Black
| valign="top" |
''' What is your favorite color? '''<br /> Red<br /> Blue<br /> Black
| valign="top" |
''' What is your favorite color? '''<br /> Red Blue Black
|-
| valign="top" |
'' 2.Possible answers''<nowiki>: </nowiki>

Red<br /> Blue<br /> Black<br /> !other
| valign="top" |
''' What is your favorite color? '''<br /> Red<br /> Blue<br /> Black<br /> Other:
| valign="top" |
''' What is your favorite color? '''<br /> Red Blue Black <br /> Other:
|-
| valign="top" |
'' 3.Possible answers:''

Red<br /> Blue<br /> Black<br /> !other=Another color:
| valign="top" |
''' What is your favorite color? '''<br /> Red<br /> Blue<br /> Black<br /> Another color:
| valign="top" |
''' What is your favorite color? '''<br /> Red Blue Black <br /> Another color:
|-
| valign="top" |
| valign="top" | Questionnaire View
| valign="top" | ''''' Text data export '''''
|-
| valign="top" |
'' 4.Possible answers: ''

red::the color of blood <br /> blue::the color of the sky <br /> black::opposite of white
| valign="top" |
''' What is your favorite color? '''<br /> the color of blood<br /> the color of the sky<br /> opposite of white
| valign="top" |
'' The "values" red, blue and black will be exported to the columns instead of standard 1, 2 and 3 numbers.<br /> See [[Viewing_Questionnaire_responses#Download_in_text_format|Download in text format]]. ''
|-
| valign="top" |
'' 5.Possible answers:''

0=Never<br /> 1=Once a year<br /> 3=Once a month<br /> 5=Once a week<br /> 7=Once a day
| valign="top" |
''' How often do you practise a sport? '''Never <br />Once a year<br />Once a month<br />Once a week<br />Once a day
| valign="top" |

|}

You may enter <tt>“!other”</tt> on a line to create an '''''optional''''' ''fill in the blank'' option. An <tt><nowiki>!other</nowiki></tt> box defaults to using the prompt ''Other:'', (or the equivalent translation for ''Other'' in the current language being used). You may change this default prompt by using the format: <tt>“!other=''prompt text”''</tt> as shown in Example #3 above.

'''Notes'''

# At the moment the length of the ''fill in the blank'' input text box is set to 25 characters and is not customizable through the online interface.
# It does not make sense to provide more than one <tt><nowiki>!other</nowiki></tt> ''fill in the blank'' option for a Radio Buttons question.
# If a respondent checks a ''fill in the blank'' option '''radio button''' and leaves the text field empty, ''a warning message will be displayed'' (upon navigating to the next page or upon submitting the questionnaire).
# If a respondent has checked a ''fill in the blank'' option '''radio button''' and has filled in the text field, and later on changes his mind and clicks a different radio button in the same question, the ''fill in the blank'' text field previously entered will be automatically emptied.
# Example #4 shows a possible "hidden" option, for exporting - in responses - named values as data instead of standard numbers. If you never export your data for studying it in stats packages you won't need this option.
# If you plan to use the ''''"Personality Test"'''' feature in your questionnaire, the number preceding each choice will be used to calculate the "score" of the section that includes this question. See https://docs.moodle.org/402/en/mod/questionnaire/personality_test#Questions

=== Rate (scale 1..5) ===
==== Example: ====
The Rate question now features extra "not yet answered" radio buttons. This is especially useful in Rate questions with a long list of choices.
[[File:03-12-2013 15-23-57.jpg]]

In case the respondent forgets to check some radio buttons, upon moving to next page or submitting, the error message will be completed with highlighting of the "not yet answered" radio buttons.

[[File:03-12-2013 15-26-58.jpg]]

==== Question editing interface: ====

[[Image:05-08-2013 14-26-37.jpg|400px]]

==== Number of scale items ====
''' Nb of scale items '''is the ''number of items'' to be used in your rate scale. You would normally use a value of 3 to 5. Default value: '''5'''.

==== Type of rate scale ====
* ''' Normal ''' (default value)
* ''' N/A columns ''' : Choose this if you want an '''N/A''' column to be added to the right of your Rate scale items columns.
* ''' No duplicate choices'''<nowiki>: Choose this if you want </nowiki>''to prevent duplicate choices in each degree '''column'''''.
** This is useful if you want the respondent to rank a number of items on a 1 to n scale and to force each rank to be unique. Example: order items A, B and C in order of preference will accept: ''A1, B3 and C2'' or ''A3, B2 and C1'', but ''it will not be possible'' for the respondent to enter: ''A1, B1, C2'' or ''A1, B2, C2,'' etc.
** Used in conjunction with [[#anchor_one|named degrees]], this '''No duplicate choices''' option can also be useful if you want the respondent to match items with named degrees, e.g. the colors ''red, blue, yellow'' with a set of physiological responses: ''excitement, tranquillity, concentration'' where '''one''' color can only match '''one''' physiological response.
* '''Osgood'''<nowiki>: Choose this to create a question of the </nowiki>[http://en.wikipedia.org/wiki/Semantic_differential Osgood's semantic differential] type. This parameter must be used in conjunction with [[#anchor_one|named degrees]].

====Possible answers====
Examples.

{| style="width: 100%" border="1" cellpadding="5"
! style="width: 50%" scope="col" valign="top" | Editing Mode
! style="width: 50%" scope="col" valign="top" | Questionnaire View
|-
| valign="top" |
''' Ex. 1 Rate''' (single line) <br /> ''Possible answers'' -> '''Enter a blank space or a short "label".'''

'''Settings: '''<br />''' Nb of scale items ''' = 5 (5 columns numbered 1...5);

'''''Type of rate scale''''' = ''Normal'' (N/A column not needed here). <br />
| valign="top" |
[[Image:05-08-2013_13-53-43.jpg|400px]]
|-
| valign="top" |
''' Ex. 2 Rate ''' (several lines)<br /> ''Possible answers''.

Blackboard<br />Desire2Learn<br />Moodle<br />Sakai<br />WebCT

''' Settings: <br />'' Nb of scale items ''''' = 4 (4 columns numbered 1...4)

'''''Type of rate scale''''' = '' N/A column ''
| valign="top" |
[[Image:05-08-2013 13-50-05.jpg]]
|-
| valign="top" |
''' Ex. 2a Rate ("ordering") '''

This option makes it impossible to click more than one radio button per column; it is thus equivalent to an "ordering" question type.

''' Settings: '''<br />''''' Nb of scale items ''''' = 3 (3 columns numbered 1...3) <br />''''' Type of rate scale''''' = ''No duplicate choices''
| valign="top" |
[[Image:05-08-2013 13-59-31.jpg|400px]]
|-
| valign="top" |
''' Ex. 3 Rate ''with named degrees '' '''<br />
''Question text'' : How would you rate the ease of use for each of the following items based on your experience with Moodle?<br />
''Possible answers'':<br />
Formatting Your Course<br />
Laying out Your Course<br />
Number of Clicks to Access Needed Content<br />
Adding Content<br />
Ability to Add/Change Themes/Appearance<br />
Overall Navigation of Moodle<br />

''Named degrees''<br />
4=Very easy to use<br />
3=Easy to use<br />
2=Somewhat difficult to use<br />
1=Difficult to use<br />

''' Settings: '''<br />''''' Nb of scale items ''''' = 4 (4 named columns) <br />''''' Type of rate scale ''''' = '' Normal '' (N/A column not needed here)
| valign="top" |
[[Image:05-08-2013 14-04-00.jpg|600px]]
|-
| valign="top" |
''' Ex. 3b Rate ''with named degrees '' '''<br /> ''Possible answers'':<br />
formatting::Formatting Your Course<br />
layout::Laying out Your Course<br />
clicks::Number of Clicks to Access Needed Content<br />
addcontent::Adding Content<br />
appearance::Ability to Add/Change Themes/Appearance<br />
navigation::Overall Navigation of Moodle<br />

''Named degrees''<br />
4=Very easy to use<br />
3=Easy to use<br />
2=Somewhat difficult to use<br />
1=Difficult to use<br />

| valign="top" |
If the choice options text is fairly long, you may use shorter "labels" immediately followed by two colons (::).
The labels "formatting", "layout", "clicks" etc. will be saved to the columns headings in the Download as text format operation, instead of the longer labels which will be displayed to the questionnaire respondent.

'''Please note''' that in former versions of Questionnaire the separator between "short label" and "options text" used to be the equal sign (=). In Questionnaire 2.5 and later, please use two colons (::) as a separator.
|-
| valign="top" |
''' Ex. 4 [http://en.wikipedia.org/wiki/Semantic_differential Osgood's Semantic differential] '''' '''<br /> Possible answers.

1=--<br /> 2=-<br /> 3=±<br /> 4=+<br /> 5=++<br /> weak|strong<br /> cold|warm<br /> cowardly|brave

''' Settings: '''<br />''''' Nb of scale items ''''' = 5 (5 named columns) <br />''''' Type of rate scale ''''' = ''Osgood''

''' Note.- ''' To separate the pairs of words you must use a pipe character '''<nowiki>|</nowiki>'''
| valign="top" |
[[Image:05-08-2013 14-06-54.jpg]]
|}

'''Notes.-''' <span id="anchor_one">'''named degrees'''</span>

For this question type you have two display options. The default option displays the [http://en.wikipedia.org/wiki/Likert_scale Likert] scale degrees as numbers (1...5). If you prefer to have named degrees instead of numbers, you'll have to enter those names in the '''''Named degrees''''' list (see '''''Example 3 ''''' above). On each line of "Named degrees" enter the degree number, ''immediately followed'' by the equal sign '''<nowiki>=</nowiki>''' ''immediately followed'' by the name you want to give to that degree.

If you plan to use the "Personality Test" feature in your questionnaire, the number preceding each named degree will be used to calculate the "score" of the section that includes this question. See https://docs.moodle.org/402/en/mod/questionnaire/personality_test#Questions_2.

If ''the number of named degrees'' in the possible answers list ''is different from the number determined by the value you entered'' in the '''Nb of scale items''' field, this will be automatically adjusted when you save the question.

Example #3b shows a possible "hidden" option, for exporting - in responses - shorter label instead of the longer text values. If you never export your data for studying it in stats packages you won't need this option. Please note that the example is provided here for the '''Rate ''with named degrees''''' question sub-type but it works for all Rate question sub-types except Osgood which requires short left and right options anyway.

===Text Box===

For the Text Box question type, enter the Input Box length and the Maximum text length of text to be entered by respondent.

Default values are 20 characters for the Input Box width and 25 characters for the maximum length of text entered.

===Yes/No===

==Manage questions==

In the '''Manage questions''' section of the Edit Questions page, you can conduct a number of operations on a Questionnaire's questions. Normally you should never add questions or delete questions in a questionnaire that is live in a moodle course, and which some students may have already responded to.

You can Move a question to a different position in the Questionnaire. If your questionnaire contains some "conditional branching" questions, you may not be able to move some of the parent or child questions to some positions which would ruin the branching.

You can Edit a question, but again, be extra careful when editing questions once students have started to complete a questionnaire.

If you try to Delete a child or parent question (in a Conditional branching questionnaire), you will be warned of the possible consequences of those deletions.

By clicking on the Green or Red dots, you can switch the "Response required" status of questions.

Please note that the numbers in front of each question in this interface are ''not'' the question numbers that will be displayed when answering the questionnaire. Here, these numbers indicate the question's position, and even non-real questions such as Labels and Page Breaks have a position number.

----
[[Category:Teacher]]

[[es:Editando preguntas de un cuestionario]]
[[fr:Ajouter_des_questions]]

Workshop grading strategies

2021-07-14T13:24:06Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Workshop}}
Simply said, selected grading strategy determines how the assessment form may look like And how the grade for a submission given by a certain assessment is calculated based on the assessment form. Workshop ships with four standard grading strategies. More strategies can be developed as pluggable extensions.

== Accumulative grading strategy ==
[[Image:Accumulative assessment form.png|200px|thumb|Assessment form using accumulative grading]]
In this case, the assessment form consists of a set of criteria. Each criterion 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.

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.

: <math>G_s = \frac{\sum_{i=1}^N \frac{g_i}{max_i} w_i }{\sum_{i=1}^N w_i}</math>
: 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.

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.

Take the case above as an example. Suppose that the third criterion uses ''scale: 6 levels''. An assessor gives grade 90 for the first criterion (or aspect 1), grade 16 for the second criterion and grade 9 ''very good'' for the last criterion. And the weights of the three criteria are 1, 2, and 3, respectively. Because for the third criterion, the scale has 6 items and grade 9 ''very good'' is the second one of the grade sequence ordered from highest to lowest, grade 9 will be mapped to 4. That is, in the formula above, g3 = 4 and max3 = 5.Then the final grade given by this assessment will be:
[[Image: Accumulative formula.png|left]]<br clear="all"/>

== Comments ==
[[Image:Comments assessment form.png|200px|thumb|right|Assessment form using comments]]
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 another one using proper grading and submissions are assessed again using a different assessment form.
<br clear="all"/>

== Number of errors ==
[[Image:Numoferror assessment form.png|200px|thumb|right|Assessment form using Number of Errors]]
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.

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.

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.

You can edit the original assessment form by following the steps below:
# Write down the corresponding description for each assertion in the blank. Then fill in the blanks of ''word for the error'' and ''word for the success''. Set the weight for each assertion. As you can see, the grade mapping table is still blank now.
# Click the ‘save and close’ button at the end of this page.
# Click the ‘Edit assessment form’ link at the shade area titled ''setup phase'' in the upper part of this page and view the assessment form again. At this time, you can see that the grade mapping table has already been set. (''Note'': Initially all the field are blank. You need to choose the right value from each list to make this grading strategy work properly.)
[[Image:Numberoferrors grade mapping table.png|300px|thumb|none|grade mapping table]]

For example, if an assessment form contains three assertions:

{| class="wikitable"
|-
! Assertion No.
! Content
! Pass or failure state
! Weight
|-
| 1
| Has the suitable title
| Yes/No
| 1
|-
| 2
| Has creative ideas
| Present/Miss
| 2
|-
| 3
| The abstract is well-written
| Yes/No
| 3
|}

In the example above, suppose that a reviewer gives one certain work ''Yes/Miss/Yes'' as the assessment. Since the submission only fails to meet the second criterion and the weight of the second criterion is 2, the total number of errors will be 2. Thus the grade for submission given by this assessment is 66%. Suppose that the maximum grade for submission set in ''grade settings'' is 100, therefore the final grade for this submission given by this assessment is grade 66.

== Rubric ==
[[Image:Rubric assessmentform list.png|200px|thumb|right|Assessment form in list mode]]
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 are provided. A number grade is assigned to each of these levels. The reviewer chooses which level answers/describes the given criterion best.

The final grade is aggregated as

: <math>G_s = \frac{\sum_{i=1}^N (g_i - min_i) }{\sum_{i=1}^N (max_i - min_i)}</math>
: where <math>g_i \in \mathbb{N}</math> is the grade given to the i-th criterion, <math>min_i \in \mathbb{N}</math> is the minimal possible grade of 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 criteria in the rubric.
[[Image:Rubric assessmentform grid.png|200px|thumb|right|Assessment Form in grid mode]]
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).

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.

''Example of calculation:'' let us have a rubric with two criteria, which both have four levels 1, 2, 3, 4. The reviewer chooses level with the grade 2 for the first criterion and the grade 3 for the second criterion. Then the final grade is:

: <math>G_s = \frac{(2 - 1) + (3 - 1)}{(4 - 1) + (4 - 1)} = \frac{3}{6} = 50 %</math>

Note that this calculation may be different from how you intuitively use rubric. For example, when the reviewer in the previous example chose both levels with the grade 1, the plain sum would be 2 points. But that is actually the lowest possible score so it maps to the grade 0. To avoid confusion, it is recommended to always include a level with the grade 0 in the rubric definition.

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

* Criterion strategy from 1.9 are replaced with Rubric 2.0 using just one dimension
* Rubric from 1.9 are by Rubric 2.0 by using point scale 0-4 for every criterion.

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.

==Experiencing Real Workshop==
If you would like to try out a real workshop, please log in to the [http://school.moodledemo.net/ School demo Moodle] with the username ''teacher'' and password ''moodle''. You can access the different stages of and explore the grading and phases of a [http://school.moodledemo.net/mod/workshop/view.php?id=651 completed workshop with data] on My home country.

[[es:Estrategias de calificación de taller]]
[[de:Bewertungsstrategien bei gegenseitigen Beurteilungen]]

Tutorship module

2021-07-14T13:24:06Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

'''Tutorship''' is a schedule tutoring sessions module for Moodle, where teachers and students can make appointments for tutoring interviews within a timetable view.

It helps to administrate and schedule tutoring hours, it allows students to make appointments with teachers for tutoring interview sessions, from a configurable time slots timetable view. Teachers can design their module timetable in order to offer the students a tutorship timetable, so that they can see and make appointments by requesting any available timetable slot.

It was first developed under Moodle version 2.0 in November 2010. It is contributed by [http://moodle.org/user/profile.php?id=1116685 Alejandro Michavila].

== Introduction ==

There are three different views depending on user roll:
;Teachers: Can manage up to three different timetables, adjust the settings that will be applied for all timetables, and they can do it within any course the teacher is enrolled in.
;Students: Can request or cancell time slots from the teacher's timetable, where current week is show by default, but next week is also available for viewing.
;Administrators: Can adjust initial module settings before any teacher adds any instance to any course.

== Features ==

=== General features ===

* Email notifications.

* Supported English and Spanish languages.

* Help icons on the Tutorship's elements like header or name field.

* Display error notifications to inform user, in case an error took place.

* Records user activity to enable audit.

* Compatibility from 2.0 upwards.

=== Student features ===

* Students can choose the teacher they want to see timetable from.

* Students can click on the time slot they want to reserve, and they can cancell their requests.

* Current week and next week time slots view from Tutorship timetable.

* Can reserve slots from tomorrow to next week's friday, up to a maximum of 4 reserves (depends on teacher's timetable configuration).

* Students will receive in their email box a confirmation or cancellation of their request, and they can also see confirmation from the timetable view.

=== Teacher features ===

* Current week and next week time slots view from Tutorship timetable.

* Can confirm or cancell reservations from the timetable view.

* Can edit the timetable and can save up to three timetables.

* Can adjust settings to all timetables, like: enable/disable sending mail to teacher, send automatic confirmations to students requests, set the number of reservation request per student (up to 4 as maximum), enable or disable student requests (students will not have the reserve link).

=== Administrator features ===

* Global settings can be adjusted from the module settings page at Administration > Modules > Activities > Tutorship.

== Installation ==

Here is a basic outline of the installation process:

# DO NOT PANIC!
# Unzip the archive and read this file.
# Move the files into your Moodle mod Web directory in moodle/mod.
# Visit Settings > Site Administration > Notifications, you should find the module's tables successfully created.
# Go to Site Administration > Modules > Activities > Manage activities, and you should find that the tutorship has been added to the list of installed modules.
# Make your global settings adjustments before adding any instance.
# You may now proceed to add a new instance of tutorship to a course.

== Uninstallation ==

Here is a basic outline of the uninstallation process:

# DO YOU REALLY WANT TO UNINSTALL?
# Go to Site Administration > Modules > Activities > Manage activities, and delete your Activity module.
# You may now proceed to remove the module files from moodle/mod.

== Synopsis ==

=== If you are a student ===

*Go to a course and click on the instance name, could be some name like "Tutoring schedule timetable", but if you are not sure, you can see the module logo at tutorship/pix/ path, see package structure for further details.

*Select a teacher from the list and turing current week timetable will be shown.

*You can choose to see current or next week available slots.

*If teacher has enabled student tutorship session request, then you can request any available slot.

*You can also cancell your reques

=== If you are a teacher ===

*Click on "Turn editing on" and select "Tutorship" from the "Add an activity" list. Type the name for your instance that will be shown to everybody or leave the "Tutoring schedule timetable" default name. Now it is ready to use.

*Go to any course you are enrolled and click on the module instance name, you will see your tutoring timetable as students see it, or empty if no timetable has been created yet.

* To create a timetable go to edit and select the period you want your timetable be related to.

* You can have three different timetables, one per period.

* You can enable or disable any time slot you want to offer as a tutoring session, it will be shown on your tutoring timetable.

* You can adjust your settings common to all timetables.

=== If you are an administrator ===

*Click on Administration > Modules > Activities > Tutorship and edit the module global configuration, taking in mind not to have any instance added to any course. Global configuration should be edited before any module instance is added to any course, otherwise negative consecuences will take place.

== Screanshots ==

[[Image:Tutorship1.png|700px]]

[[Image:Tutorship2.png|700px]]

[[Image:Tutorship3.png|700px]]

[[Image:Tutorship4.png|700px]]

== Package structure ==

tutorship/
|_ view.php - Prints a general view of tutorship.
|_ teacherview.php - Prints a particular teacher view of tutorship.
|_ studentview.php - Prints a particular student view of tutorship.
|_ locallib.php - Internal library of functions for module tutorship.
|_ lib.php - Library of interface functions for tutorship.
|_ index.php - Prints all instances provided in a course.
|_ version.php - Defines the version of tutorship.
|_ mod_form.php - The instance configuration form.
|_ settings.php - The module configuration variables.
|_ COPYING.txt - A copy of the GNU General Public License.
|_ README.txt - This info text file.
|_ lang/en/
| |_ tutorship.php - English strings for tutorship.
|_ lang/es/
| |_ tutorship.php - Spanish strings for tutorship.
|_ pix/
| |_ icon.gif - An instance icon.
|_ db/
|_ upgrade.php - The upgrade tacking file.
|_ install.xml - The data base schema definition file.
|_ access.php - The tutorship capabilities definition file.
|_ log.php - Defines log events.
|_ uninstall.php - Executed after the uninstall process.

== Database schema ==

[[Image:Tutorship.png]]

Here is the Dia file: [[Media:Tutorship.dia]]

{| class="wikitable"
|-
! Table
! Description
|-
| tutorship
| The main instance table.
|-
| tutorship_timetables
| The teacher's timetable with their timeslots.
|-
| tutorship_reserves
| The student's reserved timeslots.
|-
| tutorship_configs
| The teacher's timetable configurations.
|-
| tutorship_periods
| The timetable's periods.
|-
| tutorship_timeslots
| All the possible timeslots within a week.
|-
|}

== Languages supported ==

*English.
*Spanish.

== Supported versions ==

* 2.0.

== See also ==

*[http://download.moodle.org/download.php/plugins/mod/tutorship.zip Download latest version]
*[http://moodle.org/mod/data/view.php?d=13&rid=4347 Modules and plugins database entry]
*[http://moodle.org/mod/forum/discuss.php?d=161889 Forum discussion]
*[http://cvs.moodle.org/contrib/plugins/mod/tutorship Browse through the code]
*[http://tracker.moodle.org/browse/CONTRIB/component/10763 Bugs and issues]
*[https://docs.moodle.org/en/Installing_contributed_modules_or_plugins Installing contributed modules or plugins]

[[Category: Contributed code]]
[[es:Modulo_tutorship]]

MRBS block/import

2021-07-14T13:24:05Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

This feature works in a similar way to flatfile enrolement; it is enabled by configuring a file location in the module settings. Once there is a location set, that location will be checked every time cron runs and if a file is found it will be processed.

All existing imported bookings will be deleted from the database before the new import is processed- this is done so that a timetable can be imported regularly, ensuring that mrbs is kept up to date. Any imported bookings that have been edited will not be deleted and will not be re-imported, however any deleted bookings will be re-imported.

The file should be a csv file, without a header row, containing the following fields:
{| class="wikitable"
|-
!Start time
!End time
!Date of first session
!Weekpattern
!Room name
!Username
!Name
!Description
|-
|hh:mm format, if periods are used then see the section below
|hh:mm format, if periods are used then see the section below
|YYYY/MM/DD format
|This field enables a session to be repeated weekly, missing out weeks for holidays etc. To make a single booking just put 1 in this field, otherwise enter a string of 1s and spaces (each 1 representing a booking, each space representing a week without a booking). This string can be as long as required.
|must be the same as that held in the mrbs_room table
|this field is used to link the booking to a moodle user. It is not case sensitive and will not cause an error if no matching user is found (however if this is the case then only mrbs admins will be able to edit the booking)
|the name for the booking to have. If you want to take advantage of some other features then you should set this to the shortname of the course the booking is for (if there is a moodle course for it)
|a description for the booking
|}

====Times when periods are enabled====
MRBS stores period times as minutes past midnight, 00:00 is the time period1 starts, 00:01 is the time period1 ends and period 2 starts etc.

== Other pages about MRBS block ==
* [[MRBS block|Main page]]
* [[MRBS_block/forcebook|Force booking]]
* [[MRBS_block/usertt|User timetables]]

Development:External services security

2021-07-14T13:24:05Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Moodle_2.0}}

Descriptions of security framework for web services, also used for RSS feeds, embedded application and similar parts that can not use normal HTTP cookies.

=Overview=

Current solutions:
* user keys for gradebook import and export - see require_user_key_login() and db table ''user_private_key''
* open RSS feeds - no security at all
* chat_sid tokens - generated separately for each user in each chat
* calendar export - hash from user name, password and salt
* hacky cookie emulation in visual gradebook plugin

=Design=

==Different uses==
The external API may be used from different places:
# directly from PHP - no authentication, current user session is used ($USER, $SESSION)
# simple web service layer - easy to use and setup WS layer designed for interaction with enterprise systems (each having own single purpose user account), the protocol is stateless, username and password is sent with each request; security is enforced on multiple levels
# full WS layer with token authentication - it is more flexible and enables normal users to use some restricted parts of the WS APIs, performance might be significantly improved by emulation of sessions
# when embedding external applications - external application receives unique token which is used instead of normal browser session cookie, the session is linked to the current user session in browser, the token is automatically invalidated after logout
# RSS feeds, iCals, etc. - token login, no permanent session

==API layers==

Three layers:
# external server interface (SOAP, REST, RSS, etc.) - deals with tokens, emulates user session, parameter processing
# public PHP API - functions usable directly from PHP, list generated from inline PHP docs, need to verify '''all''' parameters and access control, may access $USER, should not manipulate $SESSION directly, must not read $_POST or $_GET
# low level internal API - as fast as possible, basic param validation, no access control, must not touch $USER, $SESSION, $_GET or $_POST, must not use has_capability() or require_login()!

==Context restrictions==
Context restriction of token validity should be effective against security problems in external applications interacting with Moodle. Some external applications do not have any access to http cookies, solution is to create temporary tokens. Context restrictions would allow us to grant external access to individual activities, courses ,etc..

=Implementation=

==PHP API==
This simplest case of using the external API. The calling call has to make sure the current $USER and $SESSION is valid. Optionally the caller may set up the context restriction manually. This should be the easiest way to start with Moodle modifications and integration with other PHP software.

==Simplified web services==
This type of web service is using simple username+password authentication (in future could be username+certificate). The communication integrity/privacy can be protected using https. Each external application is using own user account. These user accounts can not be used for normal login into moodle vie web interface.

This type of WS is intended primarily for integration with student information systems or other enterprise software.

===webservice auth plugin===
It is recommended to create separate user for each external application. The benefit of this auth type is that it can not be used for normal log-in from the web interface.

Several people questioned the security of sending username+password with each request - it is not a problem because this password is used only for web services, it can not be used for anything else. This means that the password is effectively a standard authentication token ;-) We coudl replace this password by a public certificate stored in the user profile field.

===WS entry point===
Separate php file /webservice/xxx/simpleserver.php

===external_services_users table===
Specifies which user may use each external service when restrictedusers flag set in service.

{| class="wikitable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''externalserviceid'''
| int(10)
|
| foreign key, reference external_services.id
|-
| '''userid'''
| int(10)
|
| foreign key, reference user.id
|-
| iprestriction
| varchar(255)
| NULL
| restrict access to some ips or subnets only
|-
| validuntil
| int(10)
| NULL
| invalidate after (once the date is reached the user cannot access the service)
|-
| timecreated
| int(10)
|
| time when this record added (date of the user/service relation creation)
|}

===Steps needed to configure simple web service access===

# enable web services
# create new service in some local plug-ip (add code into /local/yourplugin/db/services.php) or manually add new service with some functions
# add new user, set auth plugin to '''webservice''' (normal add user UI)
# enable web service layer plugin (admin UI)
# optionally add user into list of users that are allowed to use specific external services (admin UI)
# set up user permissions needed in function implementations. All required capabilities should be listed in the external function description.
# set up permission to use specific web services (optional, services do not need to specify required capability)

#Log as admin
#Add a new user
#Enable the Web Service Authentication plugin
#In the new user profil, change authentication method for web services
#In advance feature, enable web services
#In Plugin/Web Services/Manage protocol, enable the protocol you need
#In Plugin/Web Services/External Services, Add a new service, activate it and add some function to this service.
#If the selected service has restricted user option activated, assign the new user to this service
#If the selected service has required capability, assign this capability to the new user
#Assign the capability to use the selected protocol - you'll probably want to create a Web Service role for that
#the new user can now access web service from the enabled protocol with his username/password

==General web services==

More flexible than the WS with simplified authentication and setup. The performance may be significantly improved by emulation of sessions. The authentication is based on security tokens (user, context and purpose specific) that are generated in normal Moodle interface and then used in other external applications that are using our web services. This allows us to give only partial access to some parts of WS api, external applications and services do not need to be fully trusted.

The main drawback is that the complex configuration does not encourage admins to keep everything secured.

===external_tokens===
Stores permanent tokens for cookieless access, script runs without real session. (Later might have to add emulated session for performance reasons.)

{| class="wikitable"
! Field
! Type
! Default
! Description
|-
| '''id'''
| int(10)
| auto-incrementing
|
|-
| '''token'''
| varchar(128)
|
| private access key value
|-
| tokentype
| int(3)
|
| type of token: 0=permanent, no session; 1=linked to current browser session via sid; 2=permanent, with emulated session
|-
| userid
| int(10)
|
| foreign key, references user.id
|-
| creatorid
| int(10)
| the token creator (an administrator)
| foreign key, references user.id
|-
| externalserviceid
| int(10)
|
| foreign key, references external_services.id
|-
| sid
| varchar(128)
| NULL
| links to browser or emulated session
|-
| contextid
| int(10)
|
| security restriction, token usable only in this context, references context.id
|-
| iprestriction
| varchar(255)
| NULL
| IP address restriction, list of allowed addresses
|-
| validuntil
| int(10)
| NULL
| timestampt - valid until date
|-
| timecreated
| int(10)
|
| time when key created
|-
| lastaccess
| int(10)
|
| time when key last used for access
|}

===Steps needed to configure general web service access===

# enable general web services - global switch affecting all general web services (admin UI)
# enable web service layer plugins (admin UI)
# setup user permission which allows them to create tokens in some specific context for some specific purpose (roles UI)
# set up user permissions needed in function implementations
# set up permission to use specific web services (optional, services do not need to specify required capability)
# each user must create permanent token in specific context for specific purpose (user UI)
# user must copy/past this token to external application

==== Random all-time valid token ====
A user can use the same token to call a web service. We call this token an all-time valid token.

'''Specificity'''
* A token can be created by a Moodle administrator (administration page) or a simple Moodle user (user profil).
* An administrator has the ability to create a token for another Moodle user but not for himself neither for another administrator (for security purpose).
* A token is always linked to a Moodle user.
* A token cannot be linked to an administrator .
* A Moodle user create his own token on his profil page.
* To create a token, a user need "moodle/webservice:createtoken" capability.
* An administrator create token for other on a web service token page.
* An administrator cannot see token that he didn't create.
* A token is generated randomly and is long enough.
* A token can be used by an external web application. (by browser)
* A token can be used by a mobile application. (i.e. iphone native application)
* A token is sent by the external application at the same time that the function parameters are sent.
* When the user create a token, he must select a service (to link the token to a service). Only services that the user has capability on are displayed.
* ''ip restriction'' and ''valid until'' fields are optional.
* A Moodle user must select an aera on which the token can be valid. (course, ...) - TBD - unclear yet
* A user can only see token string if https is enabled.
* A token can be linked to only one service.

Administration: token management (valid until field is missing here):<br/>
[[Image:Admin_token.png]]

Administration: create token:<br/>
[[Image:Create_token.png]]

==Application embedding==

Similar to general WS, the token is linked to current session - when user logs out, the external token is immediately invalidated. The administration is much easier and the tokens are usually created automatically.

The external applications maybe be embedded into browser or they can be launched as separate programs (ex.: Java Web Start, Flex, external media players, etc.)

It is not necessary to use WS layers defined in /webservices/xxx/, the same infrastructure may be used in all ajax scripts that do not have access to browser cookies.

==RSS, iCALs and other feeds==

All cookie-less scripts such as RSS can use the external API and together with the permanent tokens. In fact ATOM is a nice example of RESTful protocol :-)

=See also=
* [[Development:Web services]]
* [[Development:External services description]]

[[Category:Web Services]]

Using Workshop

2021-07-14T13:24:04Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Workshop}}
This page explains how students and teachers can use the [[Workshop activity]] and explores ways to make the most of it in your Moodle course.
==Workshop phases==

The work flow for the Workshop module can be viewed as having five phases. The typical workshop activity can cover days or even weeks. The teacher switches the activity from one phase to another.

The typical workshop follows a straight path from Setup to, Submission, Assessment, Grading/Evaluation, and ending with the Closed phase. However, an advanced recursive path is also possible.

The progress of the activity is visualized in so called Workshop planner tool. It displays all Workshop phases and highlights 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.

===Setup phase===

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.

===Submission phase===

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 is restricted to the given time frame only. Submission start date (and time), submission end date (and time) or both can be specified.

The workshop submissions report allows teachers to see who has submitted and who has not, and to filter by submission and last modified:

[[File:workshopsubmisisonsreport.png|thumb|604px|center]]

A student is able to delete their own submission as long as they can still edit it and it has not been assessed. A teacher can delete any submission at any time, however if it has been assessed, they will be warned that the assessments will also be deleted and reviewers' grades may be affected.

===Assessment phase===

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.

===Grading evaluation phase===

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. See [[Workshop FAQ]] for instructions on how to publish submissions.

===Closed===

[[File:workshop final grades.png|thumb|center|500px|A closed workshop]]

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 and in the workshop. Participants may view their submissions, their submission assessments and eventually other published submissions in this phase.

==Workshop grading==

The grades for a Workshop activity are obtained gradually over several stages and are then finalised. The following scheme illustrates the process (with information about grade values stored in the database).

[[Image:workshop_grades_calculation.png|400px|thumb|left|The scheme of grades calculation in Workshop]]
<br clear="all"/>

Participants get two grades which are calculated during the Grading evaluation phase. The teacher can edit these grades while still in this phase. They will not go to the gradebook until the workshop is closed in the final phase. Note that it is possible to move between phases and even when the workshop is closed, grades could be changed directly in the gradebook if necessary.

The table below explains how the grades display:

{| class="wikitable"
|-
! Value
! Meaning
|-
| - (-) < Alice
| There is an assessment allocated to be done by Alice, but it has been neither assessed nor evaluated yet
|-
| 68 (-) < Alice
| Alice assessed the submission, giving the grade for submission 68. The grade for assessment (grading grade) has not been evaluated yet.
|-
| 23 (-) > Bob
| Bob's submission was assessed by a peer, receiving the grade for submission 23. The grade for this assessment has not been evaluated yet.
|-
| 76 (12) < Cindy
| Cindy assessed the submission, giving the grade 76. The grade for this assessment has been evaluated 12.
|-
| 67 (8) @ 4 < David
| David assessed the submission, giving the grade for submission 67, receiving the grade for this assessment 8. His assessment has weight 4
|-
| 80 (<del>20</del> / <ins>17</ins>) > Eve
| 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.
|}

=== Grade for submission ===

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. The teacher can influence the grade in two ways:

* by providing their own assessment, possibly with a higher weight than usual peer reviewers have
* by overriding the grade to a fixed value

=== Grade for assessment ===

The 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 a typical teacher's job.

During the grading evaluation phase, a Workshop subplugin is used to calculate the grades for assessment. Currently there is only one standard subplugin available called ''Comparison with the best assessment'' (other grading evaluation plugins can be found in the [https://moodle.org/plugins/browse.php?list=category&id=17 Moodle plugins directory]). The following text describes the method used by this subplugin.

Grades for assessment are displayed in the brackets () in the Workshop grades report. The final grade for assessment is calculated as the average of particular grading grades.

There is not a single formula to describe the calculation. However the process is deterministic. The workshop picks one of the assessments as the ''best'' one - that is closest to the mean of all assessments - and gives it a grade of 100%. Then it measures the 'distance' of all other assessments from this best one and gives them lower grades depending on how different they are from the best assessment (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.

If there are just two assessments per submission, the workshop cannot decide which of them is 'correct'. Imagine you have two reviewers - Alice and Bob. They both assess Cindy's submission. Alice says it is rubbish and Bob says it is excellent. There is no way of deciding who is right. So the workshop simply says - OK, you are both right and I will give you both a grade of 100% for this assessment. To prevent this, you have two options:

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

'''It's not final grades that are compared'''

It is very important to know that the grading evaluation subplugin ''Comparison with the best assessment'' does not compare the final grades. Regardless of the grading strategy used, every filled assessment form can be seen as an n-dimensional vector of 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.

To demonstrate this with an example, let us say you use the 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:

# Does the author state the goal of the research clearly? (yes/no)
# Is the research methodology described? (yes/no)
# Are references properly cited? (yes/no)

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.

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:

* Alice: yes / yes / no
* Bob: yes / yes / no
* Cindy: no / yes / yes

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

* Zeus 66% yes / 100% yes / 33% yes

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 as high.

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 assessments are compared at the level of individual responses, and not the final grades.

==Groups and Workshop==
When a workshop is used in a course using separate or visible groups and groupings, it is possible to filter by group in a drop-down menu at the Assessment phase, manual allocation page, grades report and so on.

[[File:workshopdropdown.png |thumb|none|upright=2.0|alt="Group filtering" | Group filtering drop down]]

==See also==
*[http://school.moodledemo.net/mod/workshop/view.php?id=651 Example workshop with data] Log in with username ''teacher''/password ''moodle'' and explore the grading and phases of a completed workshop on the Moodle School demo site.

* [http://www.ascilite.org.au/conferences/wellington12/2012/images/custom/cox,_julian_moodle.pdf Research paper] ''Moodle Workshop activities support peer review in Year 1 Science: present and future'' by Julian M Cox, John Paul Posada and Russell Waldron
* Using Moodle [http://moodle.org/mod/forum/view.php?id=740 Workshop module forum]
* Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=153268] where David explains a particular Workshop results

[[de:Gegenseitige Beurteilung nutzen]]
[[es:Uso de taller]]

Dataform search sort

2021-07-14T13:24:04Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

{{Dataform}}
{{Dataform Docs Note 1}}
==Using filters==

Provided the activity creator has added the filtering options to the view, you can filter and sort the displayed list of entries by
*applying a predefined filter (if exist)
*using the quick search and per page options (Quick filter)
*creating and applying your own advanced filters (My saved filters)

[[File:df-filter-display-menus.png]]

All filters are available from the filters menu dropdown.
To apply a filter, select the desired filter from the list. To un-apply the currently selected filter, select 'Choose...'.

[[File:df-filter-display-menu-options.png]]

==The Quick filter==
To display only entries that '''contain''' a certain text content in any of the (view) fields enter the text in the 'Search' input box and press Enter. This will create the Quick filter (or update it if it already exists) and apply it to the view (the Quick filter will show as selected in the filters menu). If you want to clear the search criterion from the Quick filter, clear the input box and press Enter.

To display only a certain number of entries per page, select the desired number in the Per page dropdown. Similar to the 'Search', a Quick filter will be created (or updated) and applied. If you want to clear the paging from the Quick filter, select 'Choose...' in the 'Per page' dropdown.

You have only one Quick filter and it is updated whenever you use the 'Search' and 'Per page' options. If you want to completely remove the Quick filter from the list, select '* Reset quick filter' in the filters menu.
==The Advanced (user) filter==
If Advanced filters are enabled in a view you can click the 'Advanced filter' link to open the advanced filter form. You can edit one of your saved advanced filters by first applying it to the view and then clicking the 'Advanced filter' link.

The advanced filter form allows you to add sort and search criteria on the view fields. In most cases you search/sort the field content. Some fields may have more than one search/sort element.

To define a sort criterion select the field element and the sort order (ascending|descending). The sort order dropdown of the criterion is disabled until to select the element. You can define multiple criteria and input fields for further criteria will be added to the form after filling the displayed ones and saving changes.

To define a search criterion:
*select AND|OR – Retrieved entries will match all AND criteria and at least one of the the OR criteria.
*select field – Field element.
*select IS|NOT – With NOT only entries that do not match the criterion will be retrieved.
*select operator
**Empty
**Equal
**Greater than
**Less than
**Greater or equal
**Less or equal
**Between
**Contains
**In
*Enter search string – See list below for special search string formats in some fields.

When editing a saved filter you can either update that filter or add a new filter. You can save up to 5 filters per view. Adding further filters will drop older ones from the list.

[[File:df-filter-advanced-form.png]]

===Searchable/Sortable fields===
This list includes only internal and standard fields. For search/sort options of add-on fields please consult the respective field's page.
{| class="wikitable" style="background-color:inherit;border:0;"
{{Dataform searchable sortable field table row | | [[Dataformfield entryactions|Entry actions]] | N/A }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield entryauthor|Entry author]] | {{Dataformfield entryauthor search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield entrygroup|Entry group]] | {{Dataformfield entrygroup search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield entrytime|Entry time]] | {{Dataformfield entrytime search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield checkbox|Checkbox]] | {{Dataformfield checkbox search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield commentmdl|Comment Mdl]] | {{Dataformfield commentmdl search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield entrystate|Entry state]] | {{Dataformfield entrystate search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield file|File]] | {{Dataformfield file search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield number|Number]] | {{Dataformfield number search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield picture|Picture]] | {{Dataformfield picture search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield radiobutton|Radio button]] | {{Dataformfield radiobutton search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield ratingmdl|Rating Mdl]] | {{Dataformfield ratingmdl search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield select|Select]] | {{Dataformfield select search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield selectmulti|Select (multiple)]] | {{Dataformfield selectmulti search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield text|Text]] | {{Dataformfield text search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield textarea|Text area]] | {{Dataformfield textarea search sort}} }}
{{Dataform searchable sortable field table row | | [[Dataformfield time|Time]] | {{Dataformfield time search sort}} }}
{{Dataform searchable sortable field table row |#F6F6F6| [[Dataformfield url|Url]] | {{Dataformfield url search sort}} }}
|}

DragMath equation editor

2021-07-14T13:24:03Z

Mudrd8mz: Text replacement - "class="nicetable"" to "class="wikitable""

<p class="note">'''WARNING:''' To use DragMath, you need to activate the TeX filter in Moodle. End users will also need to have a recent Java Runtime Environment installed. DragMath is no longer available in the new Atto editor introduced in Moodle 2.7. DragMath was available in the TinyMCE editor in Moodle 2.7, it is not distributed in Moodle 2.8 and later. It is available elsewhere as a third-party plugin which may be downloaded and installed by an administrator.</p>

==Introduction==
To quote the W3C [http://www.w3.org/Math/Software/mathml_software_cat_editors.html]:
This is an open-source drag and drop equation editor written in Java.
Once an expression is created the user can convert it into a variety
of different linear syntax for mathematics, including MathML, LaTeX,
Maple, Maxima or any user defined style.
Created by Christoper Sangwin and Alexander Billingsley at the University of Birmingham as part of the [http://www.stack.bham.ac.uk STACK project], DragMath allows students to build mathematical expressions using a graphical drag-and-drop interface similar in appearance to that available in a number of office productivity suites.

John Isner initially created and maintained several files that allowed for integration of DragMath with HTMLArea, Moodle's editor in 2007. DragMath was then maintained by Marc Grober until it was integrated into core Moodle with the release of Moodle 2.0. An outgrowth of the development to integrate DragMath into tinyMCE has been the development of SEE by Mauno Korpelainen (a link to those plugins can be found below.)

To use DragMath, users must have the Java Runtime Environment (JRE) version 1.5 or higher installed on their desktop computers. Most systems come with the JRE as standard equipment, so you may not have to do anything. If you need to install the JRE manually, you can download it from [http://java.com/en/download/index.jsp here]. Note that the JRE is variously known as Java software for your computer, Java Runtime Environment, the Java Runtime, Runtime Environment, Runtime, Java Virtual Machine, Virtual Machine, Java VM, JVM, VM, or Java download.

You can see a demo of the DragMath editor [http://www.dragmath.bham.ac.uk/ here]. The DragMath interface is highly intuitive and anyone can be using it productively after a few minutes of trial-and-error. If you have questions about the editor, there is a short manual [http://www.dragmath.bham.ac.uk/doc/index.html here] which also discusses the various configuration options, some of which are mentioned briefly below.

==Using DragMath==
DragMath is based on the simple idea that the User who does not know a lot of TeX (pronounced Tech) can still create mathematical formula for publishing. In this case, Moodle is the dispaly agent so the TeX formulae are then rendered to a Moodle screen. This essentially means that with little experience, any Junior High Maths teacher can generate all the formulae they need for most aspects of Maths in Moodle.

===Creating simple expressions===

To begin, click on the DragMath insertion button. This opens The DragMath interface.

[[Image:dragmath02.png|thumb|200px|center|Opening Dragmath]]

The toolbar is different than you may expect, we are used to nice neat rows of buttons, but Dragmath has to use tabs. Each tab is tab is a collection of "templates", that is each symbol is a "template" and can be dragged and dropped onto the work space.

[[Image:dragmath01.png|thumb|200px|center|The DragMath Interface]]

To end editing and insert the script into the Moodle page, click the Insert button. This simple, but not simplistic, interface is a strength of DragMath. It make it easy for even novices to create complex formulae.

{| class="wikitable" align="center"
|-
| colspan="4"|'''A sequence for DragMath - click an image to enlarge'''
|-
|[[Image:dragmath04f.png|thumb|150px|Select the Tab with the symbols required]]
|[[Image:dragmath03.png|thumb|150px|Click, hold then drag'n'drop a symbol]]
|[[Image:dragmath04.png|thumb|150px|Enter the values, select an operation symbol]]
|[[Image:dragmath04a.png|thumb|150px|Select another symbol and drag'n'drop]]
|-
|[[Image:dragmath04b.png|thumb|150px|Add an equal (or other) sign]]
|[[Image:dragmath04c.png|thumb|150px|Add in a variable, (chi in this case) ]]
|[[Image:dragmath04d.png|thumb|150px|Click Insert]]
|[[Image:dragmath04e.png|thumb|150px|See the encoded result in the editing dialog.]]
|}

This same sequence of operations apply equally for all formulae, all insertions, no matter how complex they become.

You can insert a template from the toolbar by drag and drop or by a click on the template in the tab, then clicking in the workspace.

===Creating more complex expressions===

More complex expressions are pretty much more of the same as above. Creating a simple multiplication table matrix, for example, seems complex,but in DragNath, it is actually simple:

{| class="wikitable" align="center"
|-
| colspan="4"|'''A sequence for a simple Multiplication Matrice in DragMath - click an image to enlarge'''
|-
|[[Image:dragmath05.png|thumb|150px|Select the Tab and add in the multiplier]]
|[[Image:dragmath05a.png|thumb|150px|Click, hold then drag'n'drop the Matrix symbol]]
|[[Image:dragmath05b.png|thumb|150px|Enter the values, select a equal symbol]]
|[[Image:dragmath05c.png|thumb|150px|Add in the rows required]]
|-
|[[Image:dragmath05d.png|thumb|150px|Add in the columns required]]
|[[Image:dragmath05e.png|thumb|150px|Edit the Matrice ]]
|[[Image:dragmath05f.png|thumb|150px|Add the equal symbol]]
|[[Image:dragmath05g.png|thumb|150px|Add and edit in the second Matrice.]]
|}

===Locally saving and restoring a DragMath expression===
When you press the Insert button, DragMath inserts the export string into your text and the DragMath window closes. ''The exported string can no longer be manipulated using DragMath.'' If you decide to change the string, you have two options:
*delete the string (including the dollar signs or other token) and completely recreate it using DragMath
*edit the expression by hand
You can not tell DragMath to re-read the expression and show it again in two dimensions. This is a theoretical limitation, not a limitation of DragMath.

But suppose the expression is very complicated. It would be impractical to start over just to make a simple change. Before you Insert the expression, you can save a copy of the expression (a .drgm file) to your local disk using the Save button (see screenshot). Later, if you need to make a change, you open the saved .drgm file.

[[Image:Dragmath_save_and_restore.png|DragMath instructions]]

A .drgm file contains three-dimensional representation of your mathematical expression. It is a binary file that can only be opened by DragMath.
===Additional Editing===

There are times when '''DragMath''' is not going to have a symbol or something you might want. Or perhaps you left something out of the DragMath constuctor, so you want to include it manually. Most likely, for something like the matrix created earlier, I want to go to 15, which means I have to change the structure of the matrix, and edit in some numbers. This is easily done with a little forethought. Copy and paste and delete or edit what you want and do not want.

{| class="wikitable" align="center"
|-
| colspan="4"|'''Manually editing a DragMath construction - click an image to enlarge'''
|-
|[[Image:dragmath06a.png|thumb|150px|Select, copy and paste the original matrix]]
|[[Image:dragmath06b.png|thumb|150px|Edit to what is actually required]]
|[[Image:dragmath06c.png|thumb|150px|Delete the original matrix]]
|}

Sometimes however, you just want to include something you forgot, or rather, add something that was not there in the first place.

{| class="wikitable" align="center"
|-
| colspan="4"|'''Accurately editing a DragMath construction manually - click an image to enlarge'''
|-
|[[Image:dragmath06d.png|thumb|150px|Construct the original equation]]
|[[Image:dragmath06e.png|thumb|150px|Copy, then edit to what is actually required]]
|[[Image:dragmath06f.png|thumb|150px|Return to the edited page]]
|}

==What DragMath Does and How It Does It==
===Configuration files===
DragMath allows you to create your own configuration files. That means it can be used to parse and display what you tell it to parse and display. By way of example, DragMath comes with a number of configuration files, one of which has been specifically designed to place doubledollar tokens before and after inserted text. We have seen a number of people change the TeX tokens in Modle using MathJax, and then become nonplussed that DragMath stops working. No DragMath still works, but it is likely inserting tokens that MathJax is not parsing. This can get confusing if you have more than one display technology in place. DragMath allows you to alter the tokens it inserts, so you can quite easily, for example, have DragMath insert startmath or endmath if that is what you want to use for tokens.
===Language Files===
DragMath can also use quite a few languages.
==So! You want to use DragMath but don't want to use the TeX filter?==
===What?===
Yes. Moodle devs decided that you should not use DragMath unless you used the Moodle TeX filter (yes, over objections from lots of folk.) Does that mean that the TeX filter is the best way to go? Hardly. The TeX filter is rather long in the tooth, desperately in need of revision, and essentially only provides a fallback to a mimetex binary if you have not installed a TeX distribution. There are lots of other options for Math display in Moodle, may of them much easier to configure and use!
===Procedure===
====Decoupling DragMath from the Tex Filter====
Since default configuration of tinymce (the default editor) requires that TeX filter is enabled before Dragmath plugin can be used we need to edit file lib/editor/tinymce/lib.php

First, make a copy of that file to make sure that you can revert back to the original.

Second, open the file for editing (with an appropriate editor that will not do unseen things to the contents of your file)

Third, locate lines 107-111:

if (array_key_exists('filter/tex', $filters)) {
$xdragmath = 'dragmath,';
} else {
$xdragmath = '';
}

Fourth, replace all those lines with this one line:

$xdragmath = 'dragmath,';

removing the if statement that makes DragMath visible only if the TeX filter is turned on.

Fifth, save the file.

Sixth, replace the original file lib/editor/tinymce/lib.php with this modified version.

====Setting up another display mechanism====
Now DragMath will show up in your editor, but you have no way of displaying the TeX or other code that you might insert with DragMath. You can explore the docs and the Math forum and you will find quite a few other ways to display Math in Moodle. One very popular way is to use MathJax. Under Moodle 2.x the AdditionalHtml field can be used to add the reference to MathJax and even do some configuration.
To accomplish this, as an administrator of your site go to: Site administration -> Appearance -> Additional HTML -> Within HEAD
Now, add

<link rel="stylesheet" type="text/css" href="http://jsxgraph.uni-bayreuth.de/distrib/jsxgraph.css" media="screen" />
<script type="text/javascript" src="http://jsxgraph.uni-bayreuth.de/distrib/jsxgraphcore.js"></script>
<script type="text/javascript" src="http://jsxgraph.uni-bayreuth.de/distrib/GeonextReader.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
MathJax.Hub.Config({
tex2jax: {
inlineMath: [ ['$$','$$'], ["\$","\$"], ['@i','@i'] ],
displayMath:[ ["\\[","\\["], ['@d','@d'] ],
processEscapes: true
}
});
</script>

Save changes.

Make sure that Tex filter and Algebra filter are disabled in Site administration > Plugins > Filters > Manage filters

Your moodle 2 is now using MathJax from a cloud server in cdn.mathjax.org with given delimiters (in this example double dollars and @i for inlineMath and @d for displayMath). You can choose to use other delimiters in configuration if you want or swap hat are there, BUT you may not use delimiters Moodle employs for other purposes and you need to be very careful of the syntax. You do not need to have the same token for beginning and end (for example, one could use startmath and endmath as tokens. See http://mathjax.org for additional information on these and other parameters.

"Wait!", you say. "What about the first three lines I added to AdditionalHtml?" We thought you would never ask. These lines add access to jsxgraph and GeoNextReader which you can find discussed in these forums and at the jsxgraph site, http://jsxgraph.uni-bayreuth.de/wp/ Consider this temporary, as you shoulod update the jsxgraph reference to use its cloud source. See a discussion here: http://jsxgraph.uni-bayreuth.de/wp/download/

==See Also==
* [[Advanced Maths Tools]] For an explanation of the SEE tools
* [[Using TeX Notation]] Some ideas and syntax
* [[TeX notation filter]] Turning TeX on
* [http://www.youtube.com/watch?v=mfc7umQ2xLA| A simple YouTube video] Constructing a simple equation.

*[http://www.youtube.com/watch?feature=endscreen&NR=1&v=8wfjwJTa784| Dragmath tutorial 1]
*[http://www.youtube.com/watch?v=XIuMNrvsVN8| Dragmath tutorial 2]
*[http://www.youtube.com/watch?v=g98o0fpmosQ&feature=relmfu| Dragmath tutorial 3]
*[http://www.youtube.com/watch?v=88KN2Y-pJw0&feature=relmfu| Dragmath tutorial 4]

Discussion of the transition of DragMath to Moodle core: http://moodle.org/mod/forum/discuss.php?d=125977&parent=551794

[[ca:DragMath_editor_d%27equacions]]
[[es:Editor de ecuación DragMath]]
[[fr:Dragmath]]