https://docs.moodle.org/310/en/api.php?action=feedcontributions&feedformat=atom&user=MaherneMoodleDocs - User contributions [en]2026-05-11T10:18:34ZUser contributionsMediaWiki 1.43.5https://docs.moodle.org/310/en/index.php?title=Managing_roles&diff=131567Managing roles2018-07-27T15:39:03Z<p>Maherne: /* Allow role to view */</p>
<hr />
<div>{{Roles}}<br />
Managing overall role capabilities can be done by an administrator using ''Administration > Site administration > Users > Permissions > Define roles''. This is the place to add custom roles or modify existing roles. The "Manage roles" tab, allows the system administrator to edit any one of over 350 different capabilities associated with any role. The "Allow role assignments", "Allow role overrides" and "Allow role switches" contain a matrix which give the ability for a specific role to work with other specific roles. <br />
<br />
==Manage roles==<br />
<br />
The 'Manage roles' tab contains a list of roles on your site. The edit column contains icons for editing, deleting roles and copying roles, and for moving them up or down in the list (affecting the way that roles are listed around Moodle).<br />
<br />
[[Image:Allowroletoview.png]]<br />
<br />
To edit a role:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the edit icon opposite the role you want to edit. For example "student".<br />
#On the editing role page, change permissions as required for each capability.<br />
#Scroll to the bottom of the page and click the "Save changes" button.<br />
<br />
See [[Creating custom roles]] for information about adding a new role and creating a duplicate role.<br />
<br />
==Role name localisation==<br />
<br />
If a standard role name or description is empty Moodle uses a default string from the current language pack. Custom roles can be customised using multilang syntax.<br />
<br />
You may also override the role names separately in each course.<br />
<br />
==Resetting a role==<br />
<br />
To reset a role back to the default permissions:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click on the name of the role, for example "student".<br />
#Click the 'Reset' button.<br />
<br />
Note that if you have students who have been given extra permissions at course and/or activity levels (such as forum ratings), then they will no longer be able to do this once the role has been reset to its default. A teacher would need to go back and set up these extra permissions in the course/activity levels again.<br />
<br />
==Allow role assignments==<br />
<br />
The "Allow role assignments" tab allows (or does not allow) a specific role to be able to assign specific roles to a user.<br />
<br />
<br />
===Enabling teachers to assign other teachers===<br />
By default, teachers can only assign other users the roles of non-editing teachers, students and guests. If you want teachers to be able to assign other teachers in their course, you can allow the role assignment:<br />
<br />
#Click on ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the Allow role assignments tab.<br />
#Click the checkbox where the teacher row and column intersect.<br />
#Click the "Save changes" button.<br />
<br />
==Allow role overrides==<br />
The "Allow role overrides" tab allows (or does not allow) a specific role to be able to override specific roles for a user. For example, it might allow a teacher role to override a student's role to a non-editing teacher's role. <br />
<br />
:Note that the settings only apply to roles that have the capabilities [[Capabilities/moodle/role:override|moodle/role:override]] or [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed.<br />
<br />
==Allow role switches==<br />
The "Allow role switches" tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see "Student" in the Settings > Switch role list. <br />
<br />
:Note: the selected role must also have the moodle/role:switchroles capability to be able to switch.<br />
<br />
==Allow role to view==<br />
<br />
'''New in 3.5:''' This setting allows the administrator to decide which roles users can see, search and filter by, according to their existing role.<br />
<br />
==Roles capabilities==<br />
<br />
*[[Capabilities/moodle/role:manage|Create and manage roles]]<br />
*[[Capabilities/moodle/role:assign|Assign roles to users]]<br />
*[[Capabilities/moodle/role:switchroles|Switch to other roles]]<br />
<br />
[[Category:Site administration]]<br />
<br />
[[es:Gestionar_roles]]<br />
[[eu:Rolak_kudeatu]]<br />
[[fr:Gestion des rôles]]<br />
[[ja:ロールの管理]]<br />
[[de:Rollen verwalten]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Managing_roles&diff=131566Managing roles2018-07-27T15:37:39Z<p>Maherne: Undo revision 131565 by Maherne (talk)</p>
<hr />
<div>{{Roles}}<br />
Managing overall role capabilities can be done by an administrator using ''Administration > Site administration > Users > Permissions > Define roles''. This is the place to add custom roles or modify existing roles. The "Manage roles" tab, allows the system administrator to edit any one of over 350 different capabilities associated with any role. The "Allow role assignments", "Allow role overrides" and "Allow role switches" contain a matrix which give the ability for a specific role to work with other specific roles. <br />
<br />
==Manage roles==<br />
<br />
The 'Manage roles' tab contains a list of roles on your site. The edit column contains icons for editing, deleting roles and copying roles, and for moving them up or down in the list (affecting the way that roles are listed around Moodle).<br />
<br />
[[Image:Allowroletoview.png]]<br />
<br />
To edit a role:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the edit icon opposite the role you want to edit. For example "student".<br />
#On the editing role page, change permissions as required for each capability.<br />
#Scroll to the bottom of the page and click the "Save changes" button.<br />
<br />
See [[Creating custom roles]] for information about adding a new role and creating a duplicate role.<br />
<br />
==Role name localisation==<br />
<br />
If a standard role name or description is empty Moodle uses a default string from the current language pack. Custom roles can be customised using multilang syntax.<br />
<br />
You may also override the role names separately in each course.<br />
<br />
==Resetting a role==<br />
<br />
To reset a role back to the default permissions:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click on the name of the role, for example "student".<br />
#Click the 'Reset' button.<br />
<br />
Note that if you have students who have been given extra permissions at course and/or activity levels (such as forum ratings), then they will no longer be able to do this once the role has been reset to its default. A teacher would need to go back and set up these extra permissions in the course/activity levels again.<br />
<br />
==Allow role assignments==<br />
<br />
The "Allow role assignments" tab allows (or does not allow) a specific role to be able to assign specific roles to a user.<br />
<br />
<br />
===Enabling teachers to assign other teachers===<br />
By default, teachers can only assign other users the roles of non-editing teachers, students and guests. If you want teachers to be able to assign other teachers in their course, you can allow the role assignment:<br />
<br />
#Click on ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the Allow role assignments tab.<br />
#Click the checkbox where the teacher row and column intersect.<br />
#Click the "Save changes" button.<br />
<br />
==Allow role overrides==<br />
The "Allow role overrides" tab allows (or does not allow) a specific role to be able to override specific roles for a user. For example, it might allow a teacher role to override a student's role to a non-editing teacher's role. <br />
<br />
:Note that the settings only apply to roles that have the capabilities [[Capabilities/moodle/role:override|moodle/role:override]] or [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed.<br />
<br />
==Allow role switches==<br />
The "Allow role switches" tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see "Student" in the Settings > Switch role list. <br />
<br />
:Note: the selected role must also have the moodle/role:switchroles capability to be able to switch.<br />
<br />
==Allow role to view==<br />
<br />
{{Moodle 3.4}}<br />
<br />
This setting allows the administrator to decide which roles users can see, search and filter by, according to their existing role.<br />
<br />
==Roles capabilities==<br />
<br />
*[[Capabilities/moodle/role:manage|Create and manage roles]]<br />
*[[Capabilities/moodle/role:assign|Assign roles to users]]<br />
*[[Capabilities/moodle/role:switchroles|Switch to other roles]]<br />
<br />
[[Category:Site administration]]<br />
<br />
[[es:Gestionar_roles]]<br />
[[eu:Rolak_kudeatu]]<br />
[[fr:Gestion des rôles]]<br />
[[ja:ロールの管理]]<br />
[[de:Rollen verwalten]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Managing_roles&diff=131565Managing roles2018-07-27T15:36:07Z<p>Maherne: /* Allow role to view */</p>
<hr />
<div>{{Roles}}<br />
Managing overall role capabilities can be done by an administrator using ''Administration > Site administration > Users > Permissions > Define roles''. This is the place to add custom roles or modify existing roles. The "Manage roles" tab, allows the system administrator to edit any one of over 350 different capabilities associated with any role. The "Allow role assignments", "Allow role overrides" and "Allow role switches" contain a matrix which give the ability for a specific role to work with other specific roles. <br />
<br />
==Manage roles==<br />
<br />
The 'Manage roles' tab contains a list of roles on your site. The edit column contains icons for editing, deleting roles and copying roles, and for moving them up or down in the list (affecting the way that roles are listed around Moodle).<br />
<br />
[[Image:Allowroletoview.png]]<br />
<br />
To edit a role:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the edit icon opposite the role you want to edit. For example "student".<br />
#On the editing role page, change permissions as required for each capability.<br />
#Scroll to the bottom of the page and click the "Save changes" button.<br />
<br />
See [[Creating custom roles]] for information about adding a new role and creating a duplicate role.<br />
<br />
==Role name localisation==<br />
<br />
If a standard role name or description is empty Moodle uses a default string from the current language pack. Custom roles can be customised using multilang syntax.<br />
<br />
You may also override the role names separately in each course.<br />
<br />
==Resetting a role==<br />
<br />
To reset a role back to the default permissions:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click on the name of the role, for example "student".<br />
#Click the 'Reset' button.<br />
<br />
Note that if you have students who have been given extra permissions at course and/or activity levels (such as forum ratings), then they will no longer be able to do this once the role has been reset to its default. A teacher would need to go back and set up these extra permissions in the course/activity levels again.<br />
<br />
==Allow role assignments==<br />
<br />
The "Allow role assignments" tab allows (or does not allow) a specific role to be able to assign specific roles to a user.<br />
<br />
<br />
===Enabling teachers to assign other teachers===<br />
By default, teachers can only assign other users the roles of non-editing teachers, students and guests. If you want teachers to be able to assign other teachers in their course, you can allow the role assignment:<br />
<br />
#Click on ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the Allow role assignments tab.<br />
#Click the checkbox where the teacher row and column intersect.<br />
#Click the "Save changes" button.<br />
<br />
==Allow role overrides==<br />
The "Allow role overrides" tab allows (or does not allow) a specific role to be able to override specific roles for a user. For example, it might allow a teacher role to override a student's role to a non-editing teacher's role. <br />
<br />
:Note that the settings only apply to roles that have the capabilities [[Capabilities/moodle/role:override|moodle/role:override]] or [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed.<br />
<br />
==Allow role switches==<br />
The "Allow role switches" tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see "Student" in the Settings > Switch role list. <br />
<br />
:Note: the selected role must also have the moodle/role:switchroles capability to be able to switch.<br />
<br />
==Allow role to view==<br />
<br />
{{Moodle 3.1}}<br />
<br />
This setting allows the administrator to decide which roles users can see, search and filter by, according to their existing role.<br />
<br />
==Roles capabilities==<br />
<br />
*[[Capabilities/moodle/role:manage|Create and manage roles]]<br />
*[[Capabilities/moodle/role:assign|Assign roles to users]]<br />
*[[Capabilities/moodle/role:switchroles|Switch to other roles]]<br />
<br />
[[Category:Site administration]]<br />
<br />
[[es:Gestionar_roles]]<br />
[[eu:Rolak_kudeatu]]<br />
[[fr:Gestion des rôles]]<br />
[[ja:ロールの管理]]<br />
[[de:Rollen verwalten]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Managing_roles&diff=131564Managing roles2018-07-27T15:35:58Z<p>Maherne: /* Allow role to view */</p>
<hr />
<div>{{Roles}}<br />
Managing overall role capabilities can be done by an administrator using ''Administration > Site administration > Users > Permissions > Define roles''. This is the place to add custom roles or modify existing roles. The "Manage roles" tab, allows the system administrator to edit any one of over 350 different capabilities associated with any role. The "Allow role assignments", "Allow role overrides" and "Allow role switches" contain a matrix which give the ability for a specific role to work with other specific roles. <br />
<br />
==Manage roles==<br />
<br />
The 'Manage roles' tab contains a list of roles on your site. The edit column contains icons for editing, deleting roles and copying roles, and for moving them up or down in the list (affecting the way that roles are listed around Moodle).<br />
<br />
[[Image:Allowroletoview.png]]<br />
<br />
To edit a role:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the edit icon opposite the role you want to edit. For example "student".<br />
#On the editing role page, change permissions as required for each capability.<br />
#Scroll to the bottom of the page and click the "Save changes" button.<br />
<br />
See [[Creating custom roles]] for information about adding a new role and creating a duplicate role.<br />
<br />
==Role name localisation==<br />
<br />
If a standard role name or description is empty Moodle uses a default string from the current language pack. Custom roles can be customised using multilang syntax.<br />
<br />
You may also override the role names separately in each course.<br />
<br />
==Resetting a role==<br />
<br />
To reset a role back to the default permissions:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click on the name of the role, for example "student".<br />
#Click the 'Reset' button.<br />
<br />
Note that if you have students who have been given extra permissions at course and/or activity levels (such as forum ratings), then they will no longer be able to do this once the role has been reset to its default. A teacher would need to go back and set up these extra permissions in the course/activity levels again.<br />
<br />
==Allow role assignments==<br />
<br />
The "Allow role assignments" tab allows (or does not allow) a specific role to be able to assign specific roles to a user.<br />
<br />
<br />
===Enabling teachers to assign other teachers===<br />
By default, teachers can only assign other users the roles of non-editing teachers, students and guests. If you want teachers to be able to assign other teachers in their course, you can allow the role assignment:<br />
<br />
#Click on ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the Allow role assignments tab.<br />
#Click the checkbox where the teacher row and column intersect.<br />
#Click the "Save changes" button.<br />
<br />
==Allow role overrides==<br />
The "Allow role overrides" tab allows (or does not allow) a specific role to be able to override specific roles for a user. For example, it might allow a teacher role to override a student's role to a non-editing teacher's role. <br />
<br />
:Note that the settings only apply to roles that have the capabilities [[Capabilities/moodle/role:override|moodle/role:override]] or [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed.<br />
<br />
==Allow role switches==<br />
The "Allow role switches" tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see "Student" in the Settings > Switch role list. <br />
<br />
:Note: the selected role must also have the moodle/role:switchroles capability to be able to switch.<br />
<br />
==Allow role to view==<br />
<br />
{{Moodle 3.4}}<br />
<br />
This setting allows the administrator to decide which roles users can see, search and filter by, according to their existing role.<br />
<br />
==Roles capabilities==<br />
<br />
*[[Capabilities/moodle/role:manage|Create and manage roles]]<br />
*[[Capabilities/moodle/role:assign|Assign roles to users]]<br />
*[[Capabilities/moodle/role:switchroles|Switch to other roles]]<br />
<br />
[[Category:Site administration]]<br />
<br />
[[es:Gestionar_roles]]<br />
[[eu:Rolak_kudeatu]]<br />
[[fr:Gestion des rôles]]<br />
[[ja:ロールの管理]]<br />
[[de:Rollen verwalten]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Managing_roles&diff=131563Managing roles2018-07-27T15:35:46Z<p>Maherne: /* Allow role to view */</p>
<hr />
<div>{{Roles}}<br />
Managing overall role capabilities can be done by an administrator using ''Administration > Site administration > Users > Permissions > Define roles''. This is the place to add custom roles or modify existing roles. The "Manage roles" tab, allows the system administrator to edit any one of over 350 different capabilities associated with any role. The "Allow role assignments", "Allow role overrides" and "Allow role switches" contain a matrix which give the ability for a specific role to work with other specific roles. <br />
<br />
==Manage roles==<br />
<br />
The 'Manage roles' tab contains a list of roles on your site. The edit column contains icons for editing, deleting roles and copying roles, and for moving them up or down in the list (affecting the way that roles are listed around Moodle).<br />
<br />
[[Image:Allowroletoview.png]]<br />
<br />
To edit a role:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the edit icon opposite the role you want to edit. For example "student".<br />
#On the editing role page, change permissions as required for each capability.<br />
#Scroll to the bottom of the page and click the "Save changes" button.<br />
<br />
See [[Creating custom roles]] for information about adding a new role and creating a duplicate role.<br />
<br />
==Role name localisation==<br />
<br />
If a standard role name or description is empty Moodle uses a default string from the current language pack. Custom roles can be customised using multilang syntax.<br />
<br />
You may also override the role names separately in each course.<br />
<br />
==Resetting a role==<br />
<br />
To reset a role back to the default permissions:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click on the name of the role, for example "student".<br />
#Click the 'Reset' button.<br />
<br />
Note that if you have students who have been given extra permissions at course and/or activity levels (such as forum ratings), then they will no longer be able to do this once the role has been reset to its default. A teacher would need to go back and set up these extra permissions in the course/activity levels again.<br />
<br />
==Allow role assignments==<br />
<br />
The "Allow role assignments" tab allows (or does not allow) a specific role to be able to assign specific roles to a user.<br />
<br />
<br />
===Enabling teachers to assign other teachers===<br />
By default, teachers can only assign other users the roles of non-editing teachers, students and guests. If you want teachers to be able to assign other teachers in their course, you can allow the role assignment:<br />
<br />
#Click on ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the Allow role assignments tab.<br />
#Click the checkbox where the teacher row and column intersect.<br />
#Click the "Save changes" button.<br />
<br />
==Allow role overrides==<br />
The "Allow role overrides" tab allows (or does not allow) a specific role to be able to override specific roles for a user. For example, it might allow a teacher role to override a student's role to a non-editing teacher's role. <br />
<br />
:Note that the settings only apply to roles that have the capabilities [[Capabilities/moodle/role:override|moodle/role:override]] or [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed.<br />
<br />
==Allow role switches==<br />
The "Allow role switches" tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see "Student" in the Settings > Switch role list. <br />
<br />
:Note: the selected role must also have the moodle/role:switchroles capability to be able to switch.<br />
<br />
==Allow role to view==<br />
<br />
{{Moodle 3.5}}<br />
<br />
This setting allows the administrator to decide which roles users can see, search and filter by, according to their existing role.<br />
<br />
==Roles capabilities==<br />
<br />
*[[Capabilities/moodle/role:manage|Create and manage roles]]<br />
*[[Capabilities/moodle/role:assign|Assign roles to users]]<br />
*[[Capabilities/moodle/role:switchroles|Switch to other roles]]<br />
<br />
[[Category:Site administration]]<br />
<br />
[[es:Gestionar_roles]]<br />
[[eu:Rolak_kudeatu]]<br />
[[fr:Gestion des rôles]]<br />
[[ja:ロールの管理]]<br />
[[de:Rollen verwalten]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Managing_roles&diff=131562Managing roles2018-07-27T15:35:34Z<p>Maherne: /* Allow role to view */</p>
<hr />
<div>{{Roles}}<br />
Managing overall role capabilities can be done by an administrator using ''Administration > Site administration > Users > Permissions > Define roles''. This is the place to add custom roles or modify existing roles. The "Manage roles" tab, allows the system administrator to edit any one of over 350 different capabilities associated with any role. The "Allow role assignments", "Allow role overrides" and "Allow role switches" contain a matrix which give the ability for a specific role to work with other specific roles. <br />
<br />
==Manage roles==<br />
<br />
The 'Manage roles' tab contains a list of roles on your site. The edit column contains icons for editing, deleting roles and copying roles, and for moving them up or down in the list (affecting the way that roles are listed around Moodle).<br />
<br />
[[Image:Allowroletoview.png]]<br />
<br />
To edit a role:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the edit icon opposite the role you want to edit. For example "student".<br />
#On the editing role page, change permissions as required for each capability.<br />
#Scroll to the bottom of the page and click the "Save changes" button.<br />
<br />
See [[Creating custom roles]] for information about adding a new role and creating a duplicate role.<br />
<br />
==Role name localisation==<br />
<br />
If a standard role name or description is empty Moodle uses a default string from the current language pack. Custom roles can be customised using multilang syntax.<br />
<br />
You may also override the role names separately in each course.<br />
<br />
==Resetting a role==<br />
<br />
To reset a role back to the default permissions:<br />
#Go to ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click on the name of the role, for example "student".<br />
#Click the 'Reset' button.<br />
<br />
Note that if you have students who have been given extra permissions at course and/or activity levels (such as forum ratings), then they will no longer be able to do this once the role has been reset to its default. A teacher would need to go back and set up these extra permissions in the course/activity levels again.<br />
<br />
==Allow role assignments==<br />
<br />
The "Allow role assignments" tab allows (or does not allow) a specific role to be able to assign specific roles to a user.<br />
<br />
<br />
===Enabling teachers to assign other teachers===<br />
By default, teachers can only assign other users the roles of non-editing teachers, students and guests. If you want teachers to be able to assign other teachers in their course, you can allow the role assignment:<br />
<br />
#Click on ''Administration > Site administration > Users > Permissions > Define roles''.<br />
#Click the Allow role assignments tab.<br />
#Click the checkbox where the teacher row and column intersect.<br />
#Click the "Save changes" button.<br />
<br />
==Allow role overrides==<br />
The "Allow role overrides" tab allows (or does not allow) a specific role to be able to override specific roles for a user. For example, it might allow a teacher role to override a student's role to a non-editing teacher's role. <br />
<br />
:Note that the settings only apply to roles that have the capabilities [[Capabilities/moodle/role:override|moodle/role:override]] or [[Capabilities/moodle/role:safeoverride|moodle/role:safeoverride]] allowed.<br />
<br />
==Allow role switches==<br />
The "Allow role switches" tab allows (or does not allow) a specific role to be able to temporarily change their role to another specific role. For example, this might allow a users assigned to a custom role in a course to see "Student" in the Settings > Switch role list. <br />
<br />
:Note: the selected role must also have the moodle/role:switchroles capability to be able to switch.<br />
<br />
==Allow role to view==<br />
{{Moodle 3.5}}<br />
This setting allows the administrator to decide which roles users can see, search and filter by, according to their existing role.<br />
<br />
==Roles capabilities==<br />
<br />
*[[Capabilities/moodle/role:manage|Create and manage roles]]<br />
*[[Capabilities/moodle/role:assign|Assign roles to users]]<br />
*[[Capabilities/moodle/role:switchroles|Switch to other roles]]<br />
<br />
[[Category:Site administration]]<br />
<br />
[[es:Gestionar_roles]]<br />
[[eu:Rolak_kudeatu]]<br />
[[fr:Gestion des rôles]]<br />
[[ja:ロールの管理]]<br />
[[de:Rollen verwalten]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Server_cluster&diff=128295Server cluster2017-07-19T10:26:34Z<p>Maherne: </p>
<hr />
<div>This page is going to describe some basic information related to server clustering...<br />
<br />
==Requirements==<br />
<br />
* database server - ACID compliant, for example PostgreSQL and MariaDB<br />
* main server that is able to share dataroot - locking support recommended, for example NFS<br />
* load balancer - for example Nginx<br />
* cluster nodes - web servers<br />
* Memcached server for shared caches<br />
<br />
Note: this guide is not intended for Windows OS or any other Microsoft technologies.<br />
<br />
==Initial installation==<br />
<br />
# Perform standard CLI installation on the main server using shared database and dataroot directory.<br />
# Setup web servers on cluster nodes - use local dirroot and shared database and dataroot.<br />
# Configure load balancing.<br />
<br />
==Related config.php settings==<br />
<br />
===$CFG->wwwroot===<br />
It must be the same on all nodes, it must be the public facing URL. It cannot be dynamic.<br />
<br />
===$CFG->sslproxy===<br />
Enable if you have https:// wwwroot but the SSL is done by load-balancer instead of web server.<br />
<br />
Please note that it is not compatible with $CFG->loginhttps. This is because in order for loginhttps to work, we need to know the original request, and whether it was http or https. This allows us to only provide the login form over ssl. The original request is lost when made through a "reverse" proxy / load balancer, so we cannot determine what protocol the request was made in. So we can't provide most of moodle over http and the login page over https.<br />
<br />
Enable ''Secure cookies only'' to make your site really secure, without it cookie stealing is still trivial.<br />
<br />
===$CFG->reverseproxy===<br />
Enable if your nodes are accessed via different URL.<br />
<br />
Please note that it is not compatible with $CFG->loginhttps. This is because in order for loginhttps to work, we need to know the original request, and whether it was http or https. This allows us to only provide the login form over ssl. The original request is lost when made through a "reverse" proxy / load balancer, so we cannot determine what protocol the request was made in. So we can't provide most of moodle over http and the login page over https.<br />
<br />
===$CFG->dirroot===<br />
It is strongly recommended that $CFG->dirroot (which is automatically set via realpath(config.php)) contains the same path on all nodes. It does not need to point to the same shared directory though. The reason is that some some low level code may use the dirroot value for cache invalidation.<br />
<br />
The simplest solution is to have the same directory structure on each cluster node and synchronise these during each upgrade.<br />
<br />
The dirroot should be always read only for apache process because otherwise built in plugin installation and uninstallation would get the nodes out of sync.<br />
<br />
===$CFG->dataroot===<br />
<br />
This '''MUST''' be a shared directory where each cluster node is accessing the files directly. It must be very reliable, administrators cannot manipulate files directly.<br />
<br />
Locking support is not required, if any code tries to use file locks in dataroot outside of cachedir or muc directory it is a bug.<br />
<br />
===$CFG->tempdir===<br />
<br />
This directory '''MUST''' be shared by all cluster nodes. Locking is required.<br />
<br />
===$CFG->cachedir===<br />
<br />
This directory '''MUST''' be shared by all cluster nodes. Locking is required.<br />
<br />
===$CFG->localcachedir===<br />
<br />
The difference from $CFG->cachedir is that the directory does not have to be shared by all cluster nodes, the file contents do not change. Use local fast filesystem on each cluster node.<br />
<br />
==Performance recommendations==<br />
<br />
#Use OPcache extension on all cluster nodes.<br />
#Set $CFG->localcachedir to fast local filesystem on each node.<br />
#Use one big central memcached server for all shared caches that support it.<br />
#Use local memcached instances on cluster nodes for local caches that support it.<br />
#Store user sessions in one shared memcached server. (See [[Session_handling]] for details)<br />
#Use fast local directory for dirroot on each cluster node.<br />
#Use dynamic cluster node management.<br />
#Use transparent proxy servers.<br />
<br />
==Upgrade procedure==<br />
<br />
#Disable load balancer.<br />
#Upgrade dirroot files on master server.<br />
#Perform CLI upgrade.<br />
#Manually reset all caches in cluster nodes - restart web server, delete localcachedir and temp directories, restart memcached, etc. Or delete all cluster nodes and create nodes from a new template.<br />
#Enable load balancer.<br />
<br />
==Step by step guide for server clustering in Moodle 2.6==<br />
From hardware and performance forum thread [https://moodle.org/mod/forum/discuss.php?d=251547 https://moodle.org/mod/forum/discuss.php?d=251547]<br />
<br />
* 1 Determine your specific need for caches. This involves the concepts of shared cache or local cache, disk based cache or server based cache or protocol specific cache like Memcached or MongoDB. <br />
** 1.1 If you have a slow shared disk, you might benefit from a local disk cache.<br />
** 1.2 If you have only a few users on your Moodle site, you might not want to set up a Memcached service, even if the acceleration that Memcached provides, is very significant for the user experience.<br />
** 1.3 If you want to do anything in your power for accelerating the site, you might consider MongoDB.<br />
* 2 Configure the caches, test them and verify them. There is room for improvement in the examples for cache configuration. This is probably the most difficult step.<br />
* 3 Install the cache support on server level. This may involve installing php modules or config for php modules.<br />
* 4 Create a cache instance in MUC here: example.com/cache/admin.php?action=addstore&plugin=memcached<br />
** 4.1 Give the cache instance some arbitrary name.<br />
** 4.2 All other fields have a question mark that can be clicked on for excellent help that tells you what to fill in, and the syntax (very important).<br />
** 4.3 The result should be a Configured Store Instance, with the name of your choice.<br />
* 5 The final step is to deploy the created cache instances by Editing Mappings for e.g. Language string cache in the list of Known cache definitions.<br />
** 5.1 While experimenting with this, I have found it a life saver to open a separate browser window, where the default setting is selected, so I just need to click on the Save button to revert the setting, just in case I lose contact with the site.<br />
** 5.2 Select the name of your configured store instance from the dropdown list and click on the Save button. <br />
** 5.3 Test the new cache setting. If you lose contact with the site or it behaves weirdly, try using the trick in step 1. In case of emergency you might remove the cache config file (muc/config.php) in the folder pointed to by $CFG->dataroot . It seems that Moodle writes a new default config file if it is missing.<br />
<br />
==See also==<br />
*[[Performance recommendations]]<br />
*[[Caching]]<br />
*[[:dev:Server clustering improvements proposal]]<br />
*Hardware and performance forum thread [https://moodle.org/mod/forum/discuss.php?d=251547https://moodle.org/mod/forum/discuss.php?d=251547]<br />
*How to Cluster Moodle on Multiple Servers for High Availability and Scalability [http://www.severalnines.com/blog/clustering-moodle-multiple-servers-high-availability-scalability]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=124201User:Michael Aherne2016-06-23T07:58:57Z<p>Maherne: </p>
<hr />
<div>Software Developer,<br />
VLE Team,<br />
University of Strathclyde,<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk<br />
<br />
[[User:maherne/Setting up Eclipse]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=124200User:Michael Aherne2016-06-23T07:58:26Z<p>Maherne: </p>
<hr />
<div>Software Developer,<br />
VLE Team,<br />
University of Strathclyde,<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk<br />
<br />
[[User:Michael_Aherne/Setting up Eclipse]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=124199User:Michael Aherne2016-06-23T07:57:59Z<p>Maherne: </p>
<hr />
<div>Software Developer,<br />
VLE Team,<br />
University of Strathclyde,<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk<br />
<br />
[[User:Michael Aherne/Setting up Eclipse]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=124198User:Michael Aherne2016-06-23T07:57:35Z<p>Maherne: </p>
<hr />
<div>Software Developer,<br />
VLE Team,<br />
University of Strathclyde,<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk<br />
<br />
[Setting up Eclipse]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=124197User:Michael Aherne2016-06-23T07:56:42Z<p>Maherne: </p>
<hr />
<div>Software Developer,<br />
VLE Team,<br />
University of Strathclyde,<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk<br />
<br />
[User:Michael Aherne/Setting up Eclipse]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Server_cluster&diff=109572Server cluster2014-01-30T12:16:47Z<p>Maherne: /* Performance recommendations */</p>
<hr />
<div>This page is going to describe some basic information related to server clustering...<br />
<br />
==Requirements==<br />
<br />
* database server - ACID compliant, for example PostgreSQL and MariaDB<br />
* main server that is able to share dataroot - locking support recommended, for example NFS<br />
* load balancer - for example Nginx<br />
* cluster nodes - web servers<br />
* Memcached server for shared caches<br />
<br />
Note: this guide is not intended for Windows OS or any other Microsoft technologies.<br />
<br />
==Initial installation==<br />
<br />
# Perform standard CLI installation on the main server using shared database and dataroot directory.<br />
# Setup web servers on cluster nodes - use local dirroot and shared database and dataroot.<br />
# Configure load balancing.<br />
<br />
==Related config.php settings==<br />
<br />
===$CFG->wwwroot===<br />
It must be the same on all nodes, it must be the public facing URL. It cannot be dynamic.<br />
<br />
===$CFG->sslproxy===<br />
Enable if you have https:// wwwroot but the SSL is doen by load-balancer instead of web server.<br />
<br />
Enable ''Secure cookies only'' to make your site really secure, without it cookie stealing is still trivial.<br />
<br />
===$CFG->reverseproxy===<br />
Enable if your nodes are accessed via different URL. Please note that it is not compatible with $CFG->loginhttps.<br />
<br />
===$CFG->dirroot===<br />
It is strongly recommended that $CFG->dirroot (which is automatically set via realpath(config.php)) contains the same path on all nodes. It does not need to point to the same shared directory though. The reason is that some some low level code may use the dirroot value for cache invalidation.<br />
<br />
The simplest solution is to have the same directory structure on each cluster node and synchronise these during each upgrade.<br />
<br />
The dirroot should be always read only for apache process because otherwise built in add-on installation and plugin uninstallation would get the nodes out of sync.<br />
<br />
===$CFG->dataroot===<br />
<br />
This '''MUST''' be a shared directory where each cluster node is accessing the files directly. It must be very reliable, administrators cannot manipulate files directly.<br />
<br />
Locking support is not required, if any code tries to use file locks in dataroot outside of cachedir or muc directory it is a bug.<br />
<br />
===$CFG->tempdir===<br />
<br />
It is recommended to use separate ram disks on each node. Scripts may use this directory during one request only. The contents of this directory may be deleted if there is no pending HTTP request, otherwise delete only files with older timestamps.<br />
<br />
Always purge this directory when starting cluster node, you may get some notices or temporary errors if you purge this directory while other requests are active.<br />
<br />
===$CFG->cachedir===<br />
<br />
This directory '''MUST''' be shared by all cluster nodes. Locking is required.<br />
<br />
===$CFG->localcachedir===<br />
<br />
The difference from $CFG->cachedir is that the directory does not have to be shared by all cluster nodes, the file contents do not change. Use local fast filesystem on each cluster node.<br />
<br />
==Performance recommendations==<br />
<br />
#Use OPcache extension on all cluster nodes.<br />
#Set $CFG->localcachedir to fast local filesystem on each node.<br />
#Set $CFG->tempdir to fast local filesystem on each node.<br />
#Use one big central memcached server for all shared caches that support it.<br />
#Use local memcached instances on cluster nodes for local caches that support it.<br />
#Store user sessions in one shared memcached server. (See [[Session_handling]] for details)<br />
#Use fast local directory for dirroot on each cluster node.<br />
#Use dynamic cluster node management.<br />
#Use transparent proxy servers.<br />
<br />
==Upgrade procedure==<br />
<br />
#Disable load balancer.<br />
#Upgrade dirroot files on master server.<br />
#Perform CLI upgrade.<br />
#Manually reset all caches in cluster nodes - restart web server, delete localcachedir and temp directories, restart memcached, etc. Or delete all cluster nodes and create nodes from a new template.<br />
#Enable load balancer.<br />
<br />
==Step by step guide for server clustering in Moodle 2.6==<br />
From hardware and performance forum thread [https://moodle.org/mod/forum/discuss.php?d=251547 https://moodle.org/mod/forum/discuss.php?d=251547]<br />
<br />
* 1 Determine your specific need for caches. This involves the concepts of shared cache or local cache, disk based cache or server based cache or protocol specific cache like Memcached or MongoDB. <br />
** 1.1 If you have a slow shared disk, you might benefit from a local disk cache.<br />
** 1.2 If you have only a few users on your Moodle site, you might not want to set up a Memcached service, even if the acceleration that Memcached provides, is very significant for the user experience.<br />
** 1.3 If you want to do anything in your power for accelerating the site, you might consider MongoDB.<br />
* 2 Configure the caches, test them and verify them. There is room for improvement in the examples for cache configuration. This is probably the most difficult step.<br />
* 3 Install the cache support on server level. This may involve installing php modules or config for php modules.<br />
* 4 Create a cache instance in MUC here: example.com/cache/admin.php?action=addstore&plugin=memcached<br />
** 4.1 Give the cache instance some arbitrary name.<br />
** 4.2 All other fields have a question mark that can be clicked on for excellent help that tells you what to fill in, and the syntax (very important).<br />
** 4.3 The result should be a Configured Store Instance, with the name of your choice.<br />
* 5 The final step is to deploy the created cache instances by Editing Mappings for e.g. Language string cache in the list of Known cache definitions.<br />
** 5.1 While experimenting with this, I have found it a life saver to open a separate browser window, where the default setting is selected, so I just need to click on the Save button to revert the setting, just in case I lose contact with the site.<br />
** 5.2 Select the nam of your configured store instance from the dropdown list and click on the Save button. <br />
** 5.3 Test the new cache setting. If you lose contact with the site or it behaves weirdly, try using the trick in step 1. In case of emergency you might remove the cache config file (muc/config.php) in the folder pointed to by $CFG->dataroot . It seems that Moodle writes a new default config file if it is missing.<br />
<br />
==See also==<br />
*[[Performance recommendations]]<br />
*[[Caching]]<br />
*[[:dev:Server clustering improvements proposal]]<br />
*Hardware and performance forum thread [https://moodle.org/mod/forum/discuss.php?d=251547https://moodle.org/mod/forum/discuss.php?d=251547]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Import_groups&diff=106160Import groups2013-07-24T12:05:06Z<p>Maherne: </p>
<hr />
<div>{{Grouping users}}<br />
Groups import provides a simple, easy way to create groups from a spreadsheet (CSV).<br />
<br />
To import groups<br />
*Click the 'Import groups' button in ''Settings > Course administration > Users > Groups''<br />
*Upload the CSV file (see below for file format) either by dragging and dropping into the box with the arrow (''1 below'') or by clicking "choose a file" and uploading from the [[File picker]]. (''2 below'')<br />
<br />
[[File:newimportgroups.png]]<br />
<br />
*Click the 'Import groups' button<br />
<br />
==CSV file fieldnames==<br />
<br />
The CSV file has just one required fieldname (groupname), but can include default and/or optional fieldnames<br />
<br />
* Each line of the file contains one record<br />
* Each record is a series of data separated by commas<br />
* The first record of the file is special, and contains a list of fieldnames. This defines the format of the rest of the file.<br />
<br />
<br />
'''Required fieldnames''' - These fields must be included in the first record, and defined for each column<br />
<br />
groupname<br />
<br />
'''Default fieldnames''' - These are optional - if they are not included then the values are taken from the current language and current course<br />
<br />
idnumber,coursename,lang<br />
<br />
'''Optional fieldnames'''<br />
<br />
description,enrolmentkey<br />
<br />
(Note: The field "picture" and "hidepicture" will produce a "not a valid fieldname" error when uploaded.)<br />
<br />
{{New features}}<br />
If the ''groupingname'' is included, the imported groups will be allocated to those groupings. The groupings will be created if they do not already exist:<br />
groupingname<br />
<br />
<br />
*Separation between the comma and the text can not be a blank.<br />
*Commas within the data should be encoded as &#44 - the script will automatically decode these back to commas.<br />
*For Boolean fields, use 0 for false and 1 for true.<br />
*Either idnumber or coursename can be used to identify the course. Idnumber overrides coursename. If neither is specified, the groups will be added to the current course.<br />
*Coursename is the course shortname.<br />
*Group ID numbers are for matching groups against external systems. Within a course, all group ID numbers must be unique.<br />
*The file must be in ANSI encoding, at least not be saved in UTF-8 encoding.<br />
<br />
Note: If a group is already registered in the Moodle database for a particular course, this script will return the group name for that group. Teachers are only allowed to upload groups in courses they are authorized to edit.<br />
<br />
<br />
A sample file looks like this:<br />
<br />
<pre><br />
groupname,description,enrolmentkey<br />
Team 1,Group Assignment Team 1,orange<br />
Team 2,Group Assignment Team 2,purple<br />
Team 3,Group Assignment Team 3,green<br />
</pre><br />
<br />
[[de:Gruppen importieren]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Cohort_sync&diff=99881Cohort sync2012-08-08T11:06:22Z<p>Maherne: </p>
<hr />
<div>{{Enrolment}}<br />
Cohorts, or site-wide groups, enable all members of a cohort to be enrolled in a course in one action, either manually or synchronised automatically.<br />
<br />
==Enrolling a cohort in a course==<br />
<br />
In order to actually enrol users from a Cohort into courses the ''Cohort-Sync'' Enrollment plugin needs to be added to the enrollment methods for the course. The Administrator will first need to enable the ''Cohort-Sync'' enrolment plugin site wide (''Settings > Site administration > Plugins > Enrolments'') and then add it to the required Course: (''Settings > Course administration > Users > Enrolment Methods'').<br />
<br />
<br />
[[File:Cohortsync.png]]<br />
<br />
At this stage the ''Cohort-Sync'' instance for the course is edited and the appropriate Cohort selected. The role to which the Cohort users are assigned is also selected at this point (typically Student).<br />
<br />
Visiting the ''Settings > Course administration > Users > Enrolled Users'' page will show users enrolled via the ''Cohort-Sync'' plugin. <br />
<br />
Note that, by default, a teacher cannot add this plugin to their course. It needs to be configured by an Administrator or a user with the Manager role. Also note, that the user should be a Manager on a site level, not on the category or course level, otherwise the user will not see the option. If you want the user with the Manager role on the category level to see this enrol option, then you must add some cohorts on the category level, not on the site level.<br />
<br />
The required capabilities for setting up a cohort sync are:<br />
* moodle/course:enrolconfig in the course context<br />
* moodle/cohort:config in the course context<br />
* moodle/cohort:view in the same context as category<br />
<br />
The required capabilities for manually enrolling cohort members are:<br />
* the same as cohort sync (note: this is a bug MDL-28431)<br />
* enrol/manual:enrol in course context<br />
* moodle/course:enrolreview in course context<br />
<br />
==Enrolling a cohort in a category==<br />
See [[Category enrolments]] where it is recommended that cohort sync be used in preference to category enrolments.<br />
<br />
==See also==<br />
<br />
* [[Cohorts]] for information on how to create a cohort<br />
<br />
[[de:Einschreibung über globale Gruppen]]<br />
[[ja:コーホート同期]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Development:Setting_up_Eclipse&diff=80099Development:Setting up Eclipse2011-01-06T14:43:39Z<p>Maherne: </p>
<hr />
<div>[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that some Moodle developers like to use. Other (more) popular choices are vim and emacs.<br />
<br />
However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.<br />
<br />
This article started off as a brain-dump by [[User:Tim Hunt|Tim Hunt]]. Since then, several other people have worked through it and made corrections, so the information here should be pretty accurate.<br />
<br />
Since this page was written, Eclipse 3.3 and 3.4 have been released, along with a new PHP plugin called PDT, which is better, but uses more memory. You can download an all-in-one Eclipse+PDT from http://www.eclipse.org/pdt/downloads/. The following instructions, from the section [[#Setting_the_preferences_for_Moodle_development]] mostly still apply after you have done the install, but some of the details are a bit different.--[[User:Tim Hunt|Tim Hunt]] 07:30, 31 January 2009 (CST)<br />
<br />
==Prerequisites==<br />
<br />
Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.<br />
<br />
Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux, in each case with 1GB of memory, and that is plenty.<br />
<br />
==Installing Eclipse==<br />
<br />
Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says '''Eclipse Classic'''. Choose a Mirror, and wait for the ~100MB download.<br />
<br />
You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).<br />
<br />
On Windows, unzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.<br />
<br />
On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.<br />
<br />
On Linux, unzip somewhere suitable, and make an easy way to launch it.<br />
<br />
==The first time you run Eclipse==<br />
<br />
The first time you launch Eclipse it does a bit of setup stuff, for instance, it creates a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that. <br />
<br />
For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Use this as the default and do not ask again".<br />
<br />
Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probably don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.<br />
<br />
==Installing the necessary plugins, for Eclipse Classic==<br />
<br />
The following information of this section about plugins for PHP is for Eclipse 3.4 Ganymede or before. On Eclipse 3.5 Galileo or later, a special package of Eclipse for PHP Developers has been built. Needless to install plugin for PHP anymore.<br />
<br />
By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.<br />
<br />
If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step. (On Eclipse 3.4.0 on OSX this is in '''Eclipse > Preferences > General > Network Connections''')<br />
<br />
From the '''Help''' menu choose '''Check for Updates'''.<br />
<br />
On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.<br />
<br />
The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.<br />
<br />
In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://update.phpeclipse.net/update/nightly; then click '''OK'''. Click '''Finish'''. Under '''PHPEclipse Nightly Builds''', check '''PHPeclipse'''. Click '''Finish'''. Wait while it downloads (this may take a few minutes). Click '''Install'''. You will be prompted to restart Eclipse, click '''Restart'''.<br />
<br />
''Note, there is now also another PHP editor for Eclipse. The update URL ishttp://download.eclipse.org/tools/pdt/updates/. I am just trying it--[[User:Tim Hunt|Tim Hunt]] 11:39, 7 November 2007 (CST)''<br />
<br />
Restart the wizard (from the '''Help''' menu choose '''Software Updates -> Find and Install'''). <br />
<br />
On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.<br />
<br />
Select just two things in the box "Sites to include in search":<br />
* Your newly created '''Phpeclipse Update Site'''; and<br />
* the one called '''Europa Discovery Site''' (or possibly '''Callisto Discovery Site''').<br />
Then click '''Finish'''.<br />
<br />
It goes off and sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.<br />
<br />
Eventually, you get to a new wizard for selecting and installing the updates you want (Select the features to install). The ones you want (you may have to expand and search the tree structure) are: all the '''PHPEclipse Nightly Builds''' (from your newly created PHPEclipse Update Site) and the '''Web Standard Tools (WST)''' (usually under Callisto or Europa Discovery Site --> Web and J2EE Development). <br />
<br />
Next, and very importantly, you must click the '''Select Required''' button which should resolve dependencies and remove the warning message you are probably worrying about. Then you can click the '''Next >''' button.<br />
<br />
Read and agree to all the license agreements. Then click '''Next >'''. <br />
<br />
Click '''Finish''', and wait for the plugins to download.<br />
<br />
Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation built digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.<br />
<br />
Finally, a window will pop up asking you to restart Eclipse. Do so.<br />
<br />
==Setting the preferences for Moodle development==<br />
<br />
Now go to the '''Window''' menu, and choose '''Preferences ...''' ('''Eclipse''' menu on Mac OS X).<br />
<br />
The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.<br />
<br />
===General settings===<br />
<br />
If you have strong feelings about fonts (I would hate to edit code an anything except Andale Mono), choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.<br />
<br />
Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.<br />
<br />
Under '''General -> Editors -> File Associations''', if it is not already there, add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box (use the '''Default''' button - the default will appear at the top of the list). <br />
<br />
With '''*.html''' selected in the top box, if it is not already there, add '''PHP Editor''' to the bottom box. Then select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.<br />
<br />
If you use a web proxy, enter the details under '''Network Connections'''. (Yes, I know you have entered them somewhere else before. Now you have to enter them again here. I don't know why. You just do.)<br />
<br />
===PHP Settings===<br />
<br />
Under '''General -> Editors -> Text Editors''', check '''Show line numbers''' to display line numbers in the left margin (optional). Click '''Apply'''. (When you are editing a PHP file, you could left-click in the left margin and tick the '''Show Line Numbers''' line in the contextual menu. However, this toggle only applies to plain text files, ''not'' to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.)<br />
<br />
Under '''PHPeclipse -> Browser Preview Defaults''', turn off all checkboxes (if necessary). Click '''Apply'''.<br />
<br />
Under '''PHPeclipse -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4 (if necessary). Click '''Apply'''.<br />
<br />
Under '''PHPeclipse -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments'''. Click '''Apply'''.<br />
<br />
Under '''PHPeclipse -> PHP -> Editor''', turn on '''Remove trailing spaces on editor save'''. Click '''Apply'''.<br />
<br />
Under '''PHPeclipse -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''. Click '''Apply'''.<br />
<br />
Under '''PHPeclipse -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''. Click '''Apply'''.<br />
<br />
Under '''PHPeclipse -> PHP -> Templates''', I like to define a new template to help with debugging:<br />
;Name<br />
:dump <br />
;Description<br />
:Dump a PHP variable<br />
;Pattern<br />
<pre>print_object(${word_selection}${cursor}); // DONOTCOMMIT</pre><br />
You can do other useful things with templates too. Here are two more I use:<br />
<pre>debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT</pre><br />
<pre>$$string['${word_selection}${cursor}'] = '.';</pre><br />
That is, a simple debug message with a stack trace, and a new language string.<br />
<br />
There is a really stupid bug. Under '''PHPeclipse -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So<br />
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.<br />
# Close Eclipse. <br />
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.<br />
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.<br />
# Change this line to say '''_php_include_paths=.'''<br />
# Run Eclipse again.<br />
<br />
===SSH2===<br />
Information about generating SSH2 keys for the purpose of connecting to cvs.moodle.org can be found here at https://docs.moodle.org/en/Development:SSH_key , but please finish reading this section before reading that material.<br />
<br />
The Eclipse installation has its own SSH client plugin so you do not have to use a separate ssh client in connection with your use of Eclipse (this is one reason you will be using extssh below, instead of just ext, however, if you wish you may alter the configuration to use an external client but please post news of your success and configuration). See, http://www.jcraft.com/eclipse-cvsssh2/ , for additional information on this plugin. <br />
<br />
'' Since Eclipse 3.0M6 the CVSSSH plugin is incorporated into Eclipse, [http://www.jroller.com/prane/entry/eclipse_3_0_cvs_support as "extssh" instead of "extssh2"] - --[[User:Olli Savolainen|Olli Savolainen]] 07:54, 23 June 2008 (CDT)''<br />
<br />
Please note that Eclipse is fully equipped to generate ssh2 rsa and dsa keys as well as import keys. You may encounter issues with passphrases that are too long (a bug reportedly fixed but which may still in fact be present) and some issues with using keypairs generated by other applications have been seen, so it may be best to generate a key pair with Eclipse. Additional details on how to do this will be added.<br />
<br />
Sourceforge, at http://sourceforge.net/docs/F02/ , provides instructions on how to create a SSH key for it's CVS (remember, Moodle does not use sourceforge for its CVS now and you will need to generate keys for cvs.moodle.org, not sourceforge). This is mentioned by way of general explanation, not for the purposes of providing instructions on how to generate your keys for Eclipse. To make use of the public key, login to Moodle.org and add it via the Update My Developer Information tab under CVS Developers (http://moodle.org/cvs). Remember, public keys provided to Moodle must be in the Openssh format.<br />
<br />
===CVS Settings===<br />
<br />
These are almost all hidden under the '''Team''' bit of the tree.<br />
<br />
Under '''General -> Network Connections -> SSH2 -> Key Management''', you can set up a public/private key pair. If you do this, you won't have to keep typing your password when doing CVS operations. <br />
<br />
The rest of the ones in this section are personal preferences, but I recommend them because the default settings are very irritating.<br />
<br />
Under '''Team''', set '''Perspectives''' to '''None'''.<br />
<br />
Under '''Team -> CVS''', on the '''Files and Folders''' tab, set '''Default text mode''' to '''ASCII with keyword expansion (-kkv)'''.<br />
<br />
Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.<br />
<br />
Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.<br />
<br />
===Web and XML settings===<br />
<br />
For each XXX in CSS, HTML, Javascript, XML:<br />
<br />
Under '''Web and XML -> XML Files -> Source''', choose '''Indent using spaces''' and '''indentation size''' 4.<br />
<br />
==Checking out the Moodle code==<br />
<br />
From the '''File''' menu, choose '''New -> Project ...'''.<br />
<br />
In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.<br />
<br />
Select '''Create a new repository location''', then click '''Next >'''.<br />
<br />
Fill in<br />
<div style="float: right; border: 1px solid orange; padding: 0 1em;"><br />
For anonymous CVS access use<br />
;Host<br />
:XX.cvs.moodle.org<br />
where XX.cvs.moodle.org is one of [[CVS_for_Administrators#CVS_Servers|these mirrors]]<br />
;Repository path<br />
:/cvsroot/moodle<br />
;User<br />
:anonymous<br />
;Password<br />
:(leave blank)<br />
;Connection type<br />
:pserver<br />
</div><br />
;Host<br />
:cvs.moodle.org<br />
;Repository path<br />
:/cvsroot/moodle<br />
;User<br />
:(your Moodle CVS username)<br />
;Password<br />
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)<br />
;Connection type<br />
:extssh<br />
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.<br />
<br />
On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.<br />
<br />
On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.<br />
<br />
Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.<br />
<br />
Click '''Finish'''.<br />
<br />
<br />
Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.<br />
<br />
Make up a project name. '''moodle''' would be sensible.<br />
<br />
Click '''Finish''', and wait while all the moodle files are checked out of CVS.<br />
<br />
Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.<br />
<br />
<br />
If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:<br />
* This time you can choose '''Use an existing repository location''' instead of typing all the sourceforge CVS details again.<br />
* Select the appropriate branch. If you don't see the branch you want, see [https://docs.moodle.org/en/Development:Setting_up_Eclipse#Resetting_the_branch_information this Troubleshooting tip].<br />
* Use a different project name (e.g. moodle16, moodle17, etc.).<br />
<br />
==Let your development web server know where your files are==<br />
<br />
Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.<br />
<br />
<br />
==Quick tour of some cool features, and remaining configuration changes==<br />
<br />
I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.<br />
<br />
===Navigator===<br />
<br />
To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-highlighted.<br />
<br />
===Error highlighting===<br />
<br />
In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.<br />
<br />
You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.<br />
<br />
Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.<br />
<br />
You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should find that most of the include file warnings have gone now.<br />
<br />
Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.<br />
<br />
===Outline===<br />
<br />
Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.<br />
<br />
Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.<br />
<br />
===Code navigation===<br />
<br />
In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.<br />
<br />
Hold down CTRL, move the mouse pointer over the function name '''insert_record''', then click. Eclipse should load '''dmllib.php''', and scroll you to where this function is defined. (You can also do this by clicking on the function name and pressing the F3 key.)<br />
<br />
In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.<br />
<br />
===Open resource===<br />
<br />
From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)<br />
<br />
===Multi-file search===<br />
<br />
Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.<br />
<br />
The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.<br />
<br />
===Synchronize view===<br />
<br />
I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.<br />
<br />
This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.<br />
<br />
On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.<br />
<br />
Under '''Scope''', choose '''Workspace''', then click '''Finish'''.<br />
<br />
Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project...''' That is, it is listing just the files you have edited, but not checked in yet.<br />
<br />
'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!<br />
<br />
If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.<br />
<br />
If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.<br />
<br />
However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.<br />
<br />
Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.<br />
<br />
That's all of the really important features. I'm sure you can learn everything else on your own. And you can always read the built in help!<br />
<br />
===Creating a patch===<br />
<br />
In the synchronise view, right-click an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right-click an item and choose '''Team -> Create Patch...'''.<br />
<br />
This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.<br />
<br />
On the second page, you can set some options, but normally you don't need to change the defaults which are '''Unified''' diff format, and Patch root set to '''Workspace'''. Well, sometimes it is helpful to change the second one to '''Project''' but it is not important.<br />
<br />
There is a corresponding apply patch wizard that you can use to apply a patch to a project.<br />
<br />
===Switching to another branch or version===<br />
<br />
Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.<br />
# Right click on the moodle project in the navigator view, and select '''Team -> Switch to Another Branch or Version ...'''.<br />
# choose the second radio button: '''Select the tag from the following list'''.<br />
# If the branch you want is not in the '''Matching tags''' box, see [[Development:Setting_up_Eclipse#Resetting the branch information|Resetting the branch information]] below.<br />
# Select the branch you want and click '''Finish'''.<br />
<br />
==Troubleshooting==<br />
<br />
Some tips on how to solve common problems that may crop up.<br />
<br />
===Resetting the branch information===<br />
<br />
Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:<br />
<br />
#Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").<br />
#Click on Configure tags... (not Refresh tags).<br />
#Select config-dist.php in the top left box (if this is a Moodle checkout).<br />
#Click Add Checked tags.<br />
#Click OK.<br />
#Then you will have all tags.<br />
<br />
(thanks to Tim Hunt)<br />
<br />
This info saved my day to find all branches:<br />
1. Window->Show View->Other. Select CVS->CVS Repositories.<br />
2. Context Menu->New->Repository Location...<br />
3. Fill in the location information identifying your repository and click Finish.<br />
4. Expand the newly-created repository location.<br />
5. Add the branch:<br />
1. Right-click it and expand configure branches and versions.<br />
2. Expand HEAD and select the project moodle.<br />
3. Context Menu->Configure Branches and Versions...<br />
4. In the "Browse files for tags" table, select one or more files <br />
that contain tags you would like to see (for example scroll down <br />
to find config.php).<br />
5. On the right the existing tags will appear.<br />
6. Select the tags: for example MOODLE_15_STABLE<br />
7. Click "Add Selected Tags".<br />
8. Click "OK".<br />
6. Locate branches, MOODLE_19_STABLE, moodle MOODLE_19_STABLE.<br />
7. Context Menu->Check Out As Project.<br />
("stolen" from Joan Codina Filba <br />
General developer forum -> Moodle floating "block"/toolbar released -> Re: Moodle floating "block--PATCH FOR GRADES & ASIGNMENT --PROBLEM)<br />
<br />
===Error loading php files after Ubuntu 7.04 Install===<br />
<br />
A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to:<br />
http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.<br />
<br />
After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update, I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.<br />
<br />
===Strange mouse behavior in Eclipse with Ubuntu 9.10===<br />
<br />
After upgrading to Ubuntu 9.10 I began have left mouse clicks that did not appear to be actually firing off the expected events. I stumbled across https://bugs.launchpad.net/ubuntu/+source/gtk+2.0/+bug/452938. Essentially what I did was modify /usr/bin/eclipse and added in the line: export GDK_NATIVE_WINDOWS=true so that it executes before starting Eclipse.<br />
<br />
== Related Links ==<br />
<br />
There is an excellent series of articles published by IBM on using Eclipse for Drupal developement here : [http://www-128.ibm.com/developerworks/ibm/osource/index.html Using open source software to design, develop, and deploy a collaborative Web site Tools and techniques for getting relatively complicated Web sites up and running quickly].<br />
<br />
<br />
[[Category:Developer|Eclipse]]<br />
[[Category:Developer tools|Eclipse]]<br />
<br />
[[fr:Développement:Eclipse]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=Development:Unit_tests&diff=59991Development:Unit tests2009-07-16T11:40:55Z<p>Maherne: </p>
<hr />
<div>{{Moodle 1.7}}Location: ''Administration > Reports > Unit tests''<br />
<br />
<br />
The purpose of Unit Tests is to evaluate the individual parts of a program (functions, and methods of classes) to make sure that each element individually does the right thing. Unit Tests can be one of the first steps in a quality control process for developing or tweaking Moodle code. The next steps will involve other forms of testing to ensure that these different parts work together properly. <br />
<br />
The unit testing framework is based on the [http://www.simpletest.org/ SimpleTest] framework.<br />
<br />
== Running the unit tests in Moodle ==<br />
<br />
=== Running the basic tests ===<br />
<br />
# Log in with an admin account. <br />
# Administration ► Development ► Unit tests (moodle >= 2.0, Administration ► Reports ► Unit tests Moodle <= 1.9)<br />
# Click on the '''Reports''' link near the bottom of the page.<br />
# Click the '''Run tests''' button and wait.<br />
<br />
This finds all the tests in Moodle and runs them. You can run a subset of the tests by entering a path (for example question/type) in the 'Only run tests in' box. Similarly, if a test fails, you get some links in the failure message to make it easy to re-run just those tests.<br />
<br />
== Writing new tests ==<br />
<br />
As an example, suppose we wanted to write some tests for the string_manager class in mod/quiz/editlib.php.<br />
<br />
=== Where to put the tests ===<br />
<br />
The unit test report finds tests by looking for files called 'test....php' inside folders called 'simpletest'.<br />
<br />
So, for our example, we want to create called something like '''mod/quiz/simpletest/testeditlib.php'''. The skeleton of this file should look like:<br />
<br />
<code php><br />
<?php<br />
/**<br />
* Unit tests for (some of) mod/quiz/editlib.php.<br />
*<br />
* @license http://www.gnu.org/copyleft/gpl.html GNU Public License<br />
* @package question<br />
*/<br />
<br />
if (!defined('MOODLE_INTERNAL')) {<br />
die('Direct access to this script is forbidden.'); // It must be included from a Moodle page<br />
}<br />
<br />
// Make sure the code being tested is accessible.<br />
require_once($CFG->dirroot . '/mod/quiz/editlib.php'); // Include the code to test<br />
<br />
/** This class contains the test cases for the functions in editlib.php. */<br />
class quiz_editlib_test extends UnitTestCase {<br />
function test_something() {<br />
// Do the test here.<br />
}<br />
<br />
// ... more test methods.<br />
}<br />
?><br />
</code><br />
<br />
That is, you have a class called something_test, and in that class you have lots of methods called test_something. Normally, you have one test method for each particular thing you want to test, and you should try to name the function to describe what is being tested - without making the name too ridiculously long!<br />
<br />
=== A test function ===<br />
<br />
The a test function typically looks like<br />
<br />
<code php><br />
function test_move_question_up() {<br />
// Setup fixture<br />
<br />
// Exercise SUT<br />
$newlayout = quiz_move_question_up('1,2,0', 2);<br />
<br />
// Validate outcome<br />
$this->assertEqual($newlayout, '2,1,0');<br />
<br />
// Teardown fixture<br />
<br />
}<br />
</code><br />
<br />
This is the [http://xunitpatterns.com/Four%20Phase%20Test.html four phase test pattern]. Those comments use a lot of testing jargon. The fixture is is the background situation that needs to be set up before the test runs. SUT is short for 'situation under test'. This is where you call the function or method that you want to test. Then you check to see if the function did the right thing. Finally, you have to clean up the fixture you created. With luck there is nothing to do here<br />
<br />
In this simple example, there is no setup or teardown to do. We just call the function we are testing with some sample input, and check that the return value is what we expect.<br />
<br />
=== Shared setUp and tearDown methods ===<br />
<br />
If all your test cases relate to the same area of code, then they may all need to same bit of fixture set up. For example, all the tests in lib/simpletest/teststringmanager.php need an instance of the string_manager class to test.<br />
<br />
To avoid duplicating code, you can override a method called <code>setUp()</code> that sets up the test data. If present, this method will be called before each test method. You can write a matching <code>tearDown()</code> method if there is any clean-up that needs to be done after each test case has run. For example, in lib/simpletest/teststringmanager.php there are setUp and tearDown methods that do something like:<br />
<code php><br />
public function setUp() {<br />
// ...<br />
$this->stringmanager = new string_manager(...);<br />
}<br />
<br />
public function tearDown() {<br />
$this->stringmanager = null;<br />
}<br />
</code><br />
Then, each test can use $this->stringmanager without having to worry about the details of how it is set up.<br />
<br />
=== Further information ===<br />
<br />
The ''SimpleTest'' documentation is at: http://www.simpletest.org/.<br />
<br />
== Changes to your existing code to make it work with unit testing ==<br />
<br />
The whole point of unit testing is to test each piece of functionality separately. You can only do this is only possible to isolate that function and call it individually, perhaps after setting up a few other things.<br />
<br />
Therefore, it is good if you can write your code to depend on as few other things as possible. <br />
<br />
=== Include paths ===<br />
<br />
Includes like<br />
<br />
<code php><br />
require_once('../../config.php'); // Won't work.<br />
</code><br />
<br />
won't work. Instead, the more robust option is <br />
<br />
<code php><br />
require_once(dirname(__FILE__) . '/../../config.php'); // Do this.<br />
</code><br />
<br />
=== Access to global variables ===<br />
<br />
Because your code was included from within a function, you can't access global variables until you have done a global statement.<br />
<br />
<code php><br />
require_once(dirname(__FILE__) . '/../../config.php');<br />
require_once($CFG->libdir . '/moodlelib.php'); // Won't work.<br />
</code><br />
<br />
<code php><br />
require_once(dirname(__FILE__) . '/../../config.php');<br />
<br />
global $CFG; // You need this.<br />
require_once($CFG->libdir . '/moodlelib.php'); // Will work now.<br />
</code><br />
<br />
=== Calls to global functions ===<br />
Testing a class method that calls global functions can be problematic. At least, it's always complex, because we can't control what goes on in the global functions. We can't override the global functions or mock them in our unit tests. If the global functions themselves are well tested, this may not be a big problem, but most global functions are not well tested.<br />
<br />
==== Bridge Pattern ====<br />
If your code needs to rely extensively on some public API, you could use the [http://en.wikipedia.org/wiki/Bridge_pattern bridge pattern] to decouple your code from that API. This way, when you write unit tests, you can override the bridging class or mock it, and control its outputs while you focus exclusively on testing your code.<br />
<br />
An basic example follows: Imagine that I do not trust the ''get_string()'' global function, but my code needs to use it. Initially my code has strong coupling with ''get_string()'':<br />
<br />
<code php><br />
class myclass {<br />
public function print_stuff($stuff) {<br />
echo get_string($stuff);<br />
}<br />
}<br />
</code><br />
<br />
Now let's write a bridging class to solve this coupling issue and use it instead of ''get_string()'':<br />
<br />
<code php><br />
class languageBridge {<br />
public function get_string($stuff,$module='moodle') {<br />
echo get_string($stuff, $module);<br />
}<br />
}<br />
<br />
class myclass {<br />
public $lang_bridge;<br />
public function __construct() {<br />
$this->lang_bridge = new languageBridge();<br />
}<br />
public function print_stuff($stuff) {<br />
echo $this->lang_bridge->get_string($stuff);<br />
}<br />
}<br />
</code><br />
<br />
The following is yet another example using a bridging method to decouple from the Moodle core API.<br />
<br />
<code php><br />
class workshop_api {<br />
/**<br />
* This is a method we want to unittest<br />
*/<br />
public function get_peer_reviewers($context) {<br />
static $users=null;<br />
if (is_null($users)) {<br />
$users = $this->get_users_by_capability($context, 'mod/workshop:peerassess', <br />
'u.id, u.lastname, u.firstname', 'u.lastname,u.firstname', '', '', '', '', false, false, true);<br />
}<br />
return $users;<br />
}<br />
<br />
/** <br />
* Bridging method to decouple from Moodle core API<br />
*/<br />
protected function get_users_by_capability() {<br />
$args = func_get_args();<br />
return call_user_func_array('get_users_by_capability', $args);<br />
}<br />
}<br />
</code><br />
<br />
'''Warning:''' Here are some comments on the examples above expressing that the bridge pattern should be used very carefully.<br />
<br />
* "I think that is a case of unit tests leading to worse software design, in that you are not using the standard API for something. But if you really want to unit test, I can't think of a better solution."<br />
* "I think this can be OK if used very selectively. Unfortunately I don't think it's the solution if you want to decouple the very complex and deeply nested Moodle functions from each other"<br />
* "...your code is designed to be part of Moodle, so decoupling from a standard Moodle API is perverse."<br />
<br />
== Unit testing in 2.0 ==<br />
<br />
{{Moodle 2.0}}<br />
With the Objectification of the Database libraries in Moodle 2.0, new and better approaches to Unit testing can be used. Here is a sample of a simple test case: (in course/simpletest)<br />
<br />
<code php><br />
require_once($CFG->dirroot . '/course/lib.php');<br />
<br />
global $DB;<br />
Mock::generate(get_class($DB), 'mockDB');<br />
<br />
class courselib_test extends UnitTestCase {<br />
var $realDB;<br />
<br />
function setUp() {<br />
global $DB;<br />
$this->realDB = $DB;<br />
$DB = new mockDB();<br />
}<br />
<br />
function tearDown() {<br />
global $DB;<br />
$DB = $this->realDB;<br />
}<br />
<br />
function testMoveSection() {<br />
global $DB;<br />
$course = new stdClass();<br />
$course->id = 1;<br />
<br />
$sections = array();<br />
for ($i = 1; $i < 11; $i++) {<br />
$sections[$i] = new stdClass();<br />
$sections[$i]->id = $i;<br />
$sections[$i]->section = $i - 1;<br />
}<br />
<br />
$DB->expectOnce('get_records', array('course_sections', array('course' => $course->id)));<br />
$DB->setReturnValue('get_records', $sections);<br />
$this->assertFalse(move_section($course, 2, 3));<br />
}<br />
}<br />
</code><br />
<br />
See also '''UnitTestCaseUsingDatabase''' in lib/simpletestlib.php.<br />
<br />
== Code coverage analysis==<br />
<p class="note">'''Note:''' This section is a work in progress. Please use the [[{{TALKPAGENAME}}|page comments]] or an appropriate [http://moodle.org/course/view.php?id=5 moodle.org forum] for any recommendations/suggestions for improvement.{{{info|}}}</p><br />
<br />
{{Moodle 2.0}}<br />
<br />
'''[[Wikipedia:Code_coverage|Code coverage]]''' is a technique, strongly tied with software testing, that allows to '''check and improve the quality of the tests''' by measuring the degree of source code that is being covered by them. With Moodle supporting more and more tests each day (slowly towards a '''Test Driven Development''' model) we need to integrate some tool into our development process helping to analyse the quality of ours tests.<br />
<br />
Right now (in Moodle 2.0) we are using [http://www.simpletest.org/ SimpleTest], one simple and great tool to perform all the tests. Unluckily, it doesn't support code coverage analysis at all. In the other hand, other PHP unit testing products like [http://www.phpunit.de/ PHPUnit], more complex and powerful, have built-in support for that technique, but switching to a new product is out from our current [[Roadmap]] plans.<br />
<br />
So, after some readings and comparisons, Moodle will implement its own extensions to SimpleTest, in order to fulfil the main goal of having statement/line code coverage analysis working under Moodle 2.0 onwards. To achieve this, also [http://developer.spikesource.com/projects/phpcoverage Spike PHPCoverage], a basic code-coverage tool, will be used and extended. You can find the details of the implementation of this tool at MDL-19579.<br />
<br />
=== Changes ===<br />
<br />
To enable code coverage in your tests, only a few modifications need to be performed to your current code:<br />
<br />
# Change your test classes by adding two (public static) attributes: '''$includecoverage''' and '''$excludecoverage''', both arrays, being used to inform to the code coverage tool (via reflection) about which source code files and dirs must be covered/skipped by the analysis.<br />
# Use '''[http://cvs.moodle.org/moodle/lib/simpletestcoveragelib.php?view=markup simpletestcoveragelib.php]''' instead of simpletestlib.php in your caller scripts.<br />
# Use the '''autogroup_test_coverage''' class instead of the AutoGroupTest one (see below for details) in your caller scripts.<br />
<br />
(note that only the 1st point above is needed for new unit tests being created because both 2 and 3 (changes in caller scripts) are already implemented in Moodle and awaiting your cool unit tests.<br />
<br />
That's all! With those 3 basic changes, you will end with a complete code coverage report available for further analysis.<br />
<br />
=== API ===<br />
<br />
When using code coverage within Moodle there are two alternative APIs available, both providing the same code coverage reports at the end, but doing that in a different way. Here they are:<br />
<br />
* '''Internal (hidden) coverage API''': This API is completely hidden beyond the Unit testing API and you won't need to know the details about it. Just perform the 1-2-3 changes described above and, after running the tests you'll get the final report available for being used immediately, without needing to perform anything in your code. His major drawback: it only can perform '''one''' "code coverage session" (a.k.a. instrumentation), so it's only suitable for testing scripts using only one unit test execution. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/index.php?view=markup admin/report/unittest/index.php] where only one (big) test-group is executed.<br />
* '''External (explicit) coverage API''': This API needs extra coding as long as coverage instantiating, configuration and report generation happens in the main script. It's a bit more complex but, in the other hand, it support '''multiple''' instrumentations to be performed, and gives you more control about the code coverage process. One example of this type of unit testing is [http://cvs.moodle.org/moodle/admin/report/unittest/dbtest.php?view=markup admin/report/unittest/dbtest.php] where multiple (one for each DB being tested) test-group are executed.<br />
<br />
So, first of all (point 1 in prev section - usage), we need to define, for each unit test, which files / directories (relative to dirroot) we want to analyse with the tool. Here it's one example, for the '''dml_test''' unit test ([http://cvs.moodle.org/moodle/lib/dml/simpletest/testdml.php?view=markup /lib/dml/simpletest/testdml.php]), all we need to add to these lines to the class declaration :<br />
<br />
<code php><br />
public static $includecoverage = array('lib/dml');<br />
public static $excludecoverage = array('lib/dml/somedir');<br />
</code><br />
<br />
By doing so, the code coverage tool will know which are the target files to perform coverage analysis/reporting and will do that for all the files (recursively) in the ''lib/dml''' dir but excluding the ''lib/dml/somedir'' directory (recursively too). Note that both attributes are arrays so multiple paths can be specified in any of them. Also note that the dir where the UnitTest is stored is automatically excluded (usually ''simpletest'' dirs).<br />
<br />
And, as said, that's all you need to fulfil in order to get current/new unit tests being analysed by the code coverage tool by current Moodle scripts. The documentation below is only interesting for developers wanting to create new scripts able to perform unit testing with code coverage (points 2 and 3 in prev section - usage).<br />
<br />
==== Internal coverage API ====<br />
<code php><br />
$test = new autogroup_test_coverage($showsearch, $test_name, $performcoverage, $coveragename, $coveragedir);<br />
</code><br />
Create one new autogroup test object with code coverage support, there you can specify if you want to perform coverage (true/false), the name of the report (title) and the directory where the final report will be created (under moodledata/codecoverage). <br />
Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case the defined in point 1 aren't enough).<br />
<code php><br />
$test->add_coverage_include_path($path);<br />
$test->add_coverage_exclude_path($path);<br />
</code><br />
And then, affter adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support to end with a nice code coverage report under ''dataroot/codecoverage/$coveragedir'':<br />
<code php><br />
$test->run($unit_test_reporter);<br />
</code><br />
(don't forget that this API supports only '''one''' instrumentation to be performed)<br />
<br />
And that's all!<br />
<br />
==== External coverage API ====<br />
<code php><br />
$covreporter = new moodle_coverage_reporter($coveragename, $coveragedir);<br />
$covrecorder = new moodle_coverage_recorder($covreporter);<br />
</code><br />
Create one coverage reporter, by passing its title and output directory as parameters.<br />
<code php><br />
$test = new autogroup_test_coverage($showsearch, $test_name, $performcoverage);<br />
</code><br />
Create one new autogroup test object with code coverage support, you don't need to specify the title and dir here (as already have been defined by the moodle_coverage_reporter object).<br />
Optionally you can add more files and directories (relative to dirroot) to the list of files to be covered / ignored by using these functions (in case the defined in point 1 aren't enough).<br />
<code php><br />
$test->add_coverage_include_path($path);<br />
$test->add_coverage_exclude_path($path);<br />
</code><br />
Then, after adding a bunch of unit tests to the group, you simply invoke the test execution with code coverage support with:<br />
<code php><br />
$test->run_with_external_coverage($unit_test_reporter, $covrecorder);<br />
</code><br />
(don't forget that this API supports '''multiple''' instrumentations to be performed)<br />
<br />
And finally, you generate the code coverage report (under ''dataroot/codecoverage/$coveragedir'') using:<br />
<code php><br />
$covrecorder->generate_report();<br />
</code><br />
Once more, that's all!<br />
<br />
==== Final notes ====<br />
* Note that there are some more methods available in the moodle_coverage_recorder class. They will allow to control starting/stopping instrumentations by hand and other minor things but they shouldn't really be used. The run() and run_with_external_coverage() methods should be enough in 99% of cases.<br />
* Not being part of the API, but used by it, there is one '''[http://cvs.moodle.org/moodle/admin/report/unittest/coveragefile.php?view=markup overagefile.php]''' script under ''admin/report/unittest'' responsible for serving the coverage report files from within Moodle. See current scripts in that dir to see how can be used.<br />
* All the test execution / reporting / coverage utilities must be protected with the 'moodle/site:config' permission.<br />
<br />
== A warning ==<br />
<br />
In 'xUnit Test Patterns' there is a [http://xunitpatterns.com/TestAutomationRoadmap.html scale of testing difficulty] that goes from 1. to 6. Moodle is definitely at number 6. on that scale 'Non-object-oriented legacy software'. It then goes recommend that you don't start to learn about unit testing with that sort of software :-(<br />
<br />
== Further reading about unit testing ==<br />
<br />
[http://manning.com/reiersol/ PHP in Action] has an excellent chapter explaining unit testing in PHP with ''simpletest''. (Although the rest of that book advocates a style of programming that is very different from the style used in Moodle.)<br />
<br />
[http://www.pragprog.com/titles/utj/pragmatic-unit-testing-in-java-with-junit Pragmatic Unit Testing in Java with JUnit] is also a very good introduction, despite being in the wrong programming language. JUnit and Simpletest are very similar.<br />
<br />
[http://xunitpatterns.com/ xUnit Test Patterns] is the ultimate unit test book. I think it teaches you everything you could learn about unit testing by reading a book. The only way to learn more would be years of experience. It has really great advice for dealing with the kind of messy problems you get in a big, real project like Moodle. <br />
<br />
{{CategoryDeveloper}}<br />
[[Category:Quality Assurance]]</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=39425User:Michael Aherne2008-07-11T11:26:44Z<p>Maherne: </p>
<hr />
<div>Software Developer,<br />
VLE Team,<br />
University of Strathclyde,<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk</div>Mahernehttps://docs.moodle.org/310/en/index.php?title=User:Michael_Aherne&diff=39424User:Michael Aherne2008-07-11T11:26:25Z<p>Maherne: New page: Software Developer VLE Team University of Strathclyde Glasgow, Scotland michael.aherne@strath.ac.uk</p>
<hr />
<div>Software Developer<br />
VLE Team<br />
University of Strathclyde<br />
Glasgow, Scotland<br />
<br />
michael.aherne@strath.ac.uk</div>Maherne