MoodleDocs - User contributions [en]

Talk:New permissions evaluation in 2.0

2016-03-31T10:12:50Z

Abhijit13: Created page with "In the file Allowed_roles.png the third table has entry "Non Editing Teacher" in Column "Assignments", and row "Forum". What does it mean?"

In the file Allowed_roles.png

the third table has entry "Non Editing Teacher" in Column "Assignments", and row "Forum". What does it mean?

Role archetypes

2016-03-30T06:13:08Z

Abhijit13:

{{Infobox Project
|name = Role archetypes
|state = Implemented
|tracker = MDL-21772
|discussion = n/a
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]]
}}
{{Moodle 2.0}}

=Goals=
* Remove all roles legacy stuff
* Cleanup guest access
* Prevent accidental breaking of admin roles
* Improve performance
* Simplify coding style
* Fix some other long standing design problems

=Legacy capabilities=
Since 1.7 roles could be marked by setting legacy capabilities. Originally this was intended as a temporary solution for replacing of isteacher(), isstudent(), but we soon realised we need it also for upgrades when adding new capabilities and also for role resetting. Later the legacy capabilities were used for role related default settings.

Legacy guest capability was used for different purposes - course guest access and preventing students from posting.

=Role archetypes=
Role archetype can be specified in a new field in role table. The difference is that the code is significantly simplified and it is not possible to use the legacy capability checks at all (we have to finally solve all legacy problems).

=Redefined guest access=
Originally guests had both moodle/course:view and moodle/legacy:guest, this lead to many problems because the moodle/course:view was not used exclusively for enrolments. The guest access can be fully implemented in require_login() without any giving any capability.

=Redefined moodle/course:view capability=
The hidden role assignments were implemented to work around the single moodle/course:view capability that was used both for enrolled users and managers or admins. Unfortunately this was very hacky solution that required hacks all over the place and was never completely implemented. Now the moodle/course:view is allowing users to enter the course without actually participating in course. They are mostly invisible to other users.

The old course:view is now replaced by records in user_enrolments table.

=Admins without a role=
Since 1.7 we just kept adding hacks for hiding of administrators over and over again, we had to implement various hacks in order to protect the admin users. Solution is very simple - do not create any admin role and instead just keep the list of admins only in $CFG->siteadmins. moodle/course:view capability grants admins the right to enter any course.

Benefits:
* admins are not returned from get_users_by_capability() - no need for $doanything there
* has_capability() - the only place where $doanything makes sense
* is_siteadmin() is extremely fast because it does not need any DB access
* much safer - nobody may get doanything capability
* no admin my_courses() exceptions needed
* nobody may "break" admins anymore

=New Manager role=
Manager role is supposed to replace original "small administrators" that were assigned at a course category level. moodle/course:view capability grants admins the right to enter managed course. Admins assigned in lower levels can be automatically migrated to manager role assignments. Managers are by default not enrolled in courses, they can enter them and manage them only.

Benefits:
* better control
* much easier to setup manager of course categories

Potential problems:
* we already have "course manager" admin setting which marks roles responsible for course enrolment

=See also=
* [[Enrolment usage overview]]
* [[Enrolment rewrite and role tweaks proposal]]
* [[New permissions evaluation in 2.0]]

[[Category:Enrolment]]
[[Category:Roles]]

Roles

2016-03-30T04:11:17Z

Abhijit13:

==Definitions==

* A '''role''' is an identifier of the user's status in some context. For example: Teacher, Student and Forum moderator are examples of roles.

* A '''capability''' is a description of some particular Moodle feature. Capabilities are associated with roles. For example, ''mod/forum:replypost'' is a capability.

* A '''permission''' is some value that is assigned for a capability for a particular role. For example, allow or prevent.

* A '''context''' is a "space" in the Moodle, such as courses, activity modules, blocks etc.

==The system prior to v1.7==

In versions prior to v1.7, Moodle uses a fixed set of roles i.e. primary admin, admins, course creators, editing teachers, non-editing teachers, students, and guests. For each role, the capability or actions that they can perform are fixed. For example, the role student allows the user to submit an assignment, but doesn't allow the user to browse/edit other users' work. By using this setup we limit ourselves to a rather rigid set of capabilities for each role. If we want, say a particular student or group to be able to mark assignments in a particular course, we can't do that without giving these users teacher privileges.

==The new roles and capability system==

With v1.7 and greater, Moodle introduces a roles and capabilities system.

=== Roles ===
Role has two primary functions:
# define list of permissions - role definition is global for all contexts, but can be changed by local context overrides
# replace old course enrolments in Moodle 1.7-1.9 - role assignment in course context is similar to the old enrolment process

The new system will allow authorized users to define an arbitrary number of roles (eg a teacher)

A role consists of a list of permissions for different possible actions within Moodle (eg delete discussions, add activities etc)

Roles can be applied to users in a ''context'' (eg assign Fred as a teacher in a particular course)

=== Context ===
Here are the possible contexts, listed from the most general to the most specific.

[[Image:Moodle-contexts-1.8.png|right|thumbnail|200px|A diagram of the contexts in Moodle. Click on the diagram to see a more detailed view of it.]]

{| class="nicetable"
|-
! CONTEXT NAME
! CONTEXT AREA
! CONTEXTLEVEL
|-
| CONTEXT_SYSTEM
| the whole site
| 10
|-
| CONTEXT_USER
| another user
| 30
|-
| CONTEXT_COURSECAT
| a course category
| 40
|-
| CONTEXT_COURSE
| a course
| 50
|-
| CONTEXT_MODULE
| an activity module
| 70
|-
| CONTEXT_BLOCK
| a block
| 80
|}

Please note that CONTEXT_PERSONAL (present in 1.7-1.8) was never implemented and was removed in 1.9. CONTEXT_GROUP is also not implemented and can not be used.

An authorized user will be able to assign an arbitrary number of roles to each user in any context.

(See [[Roles and modules#Context]] for more information.)

=== Capabilities ===
Capabilities can have the following permissions:

#CAP_INHERIT
#CAP_ALLOW
#CAP_PREVENT
#CAP_PROHIBIT

If no permission is defined, then the capability permission is inherited from a context that is more general than the current context. If we define different permission values for the same capability in different contexts, we say that we are overriding the capability in the more specific context.

=== Checking for capabilities ===
You can use the [[Roles_and_modules#has_capability_.28.24capability.2C_.24contextid.2C_.24kill.29|has_capability ()]] function for checking for capabilities in your code.

=== Capability conflicts ===
Since the capabilities in each role could be different, there could be conflict in capabilities. This is resolved using different methods in versions below Moodle 2.0.

If we set a PROHIBIT on a capability, it means that the capability cannot be overridden and will ALWAYS have a permission of prevent (deny). Prohibit always wins. For example, Jeff has a naughty student role that prohibits him from postings in any forums (for the whole site), but he's also assigned a facilitator role in "Science forum" in the course Science and Math 101. Since prohibit always wins, Jeff is unable to post in "Science forum".

===Capability-locality changes in v1.9===

When resolving conflicts between "allow" and "prevent" in v1.7 and v1.8 the locality of the capability is taken into account, although with less weight than the locality of the role assignment. In v1.9 the process has been reworked, we consider locality of the role assignment when dealing with allow/prevent conflicts, but ignore where the capability has been defined (as long as it applies to the context).

Allow and prevent will cancel each other out if set for the same capability at the same context level. If this happens, we refer to the previous context level to determine the permission for the capability. This may sound more complex than it really is in practice. The upshot is that the system can be flexible enough to allow pretty much any combination of permissions.

For example - for the situation where there is

* two roles assigned to one user in a context (eg student role and teacher role)
* one override on one of those roles ( eg student role), at the same context

then

* '''1.7/1.8''' The override used to ''always'' win over the settings from the combined roles.

* '''1.9''' The override is combined with the student role first. and then the roles are combined. This is more logical, as the override is acting like a modification to the student role.

For more details, see [http://tracker.moodle.org/browse/MDL-11218 MDL-11218]

===New permissions evaluation in 2.0===

The permission evaluation changes introduced in 1.9 were too complex for majority of uses, the permission evaluation was finally simplified in Moodle 2.0 - see [[New permissions evaluation in 2.0]].

==Upgrading from 1.6==

A smooth upgrade will be provided with 1.7. The existing roles (admin, teacher, student, etc), and the existing capabilities will be automatically retained. This is done by creating default roles at site/course levels, and assigning the current users to these roles accordingly. The default roles will have default capabilities associated with them, mirroring what we have in 1.6. With no modifications, Moodle will operate exactly the same before and after the upgrade.

===Admins===

Admin users will be assigned the default legacy admin role in the system (site) context in Moodle 1.7-1.9. In Moodle 2.0 admins do not have any role assigned at all, this role was replaced by Manager role.

===Course Creators===

Course Creators will be assigned the default legacy course creator role in the system (site) context. Course creators are intended to create course only, nothing else! Once the creator creates a new course they are usually enrolled into course with default creator role.

===Teachers===

Users who were teachers will be assigned the default legacy teacher role (or non-editing teacher role) in all courses they were teacher.

===Students===

Users who were students will be assigned the default student role in all courses they were student.

===Guests===

There will still be a single guest user with no default role at site level. For each course that allows guest access, the guest role will be assigned to the guest user for that course context. The guest control for the course will be modified from three to two options (guests always need to enter enrolment key - on/off). This setting is checked as now to force guests to enter key.

==Capabilities==

This will be a comprehensive list of capabilities (it's not complete yet). It is important that capability names are unique.

===Core-level Capabilities===

Moodle core capability names start with 'moodle/'. The next word indicates what type of core capability it is, and the last word is the actual capability itself. The capabilities for the Moodle core are defined in lib/db/access.php

#moodle/legacy:guest - legacy capabilities are used to transition existing users to the new roles system during the upgrade to Moodle 1.7
#moodle/legacy:student
#moodle/legacy:teacher
#moodle/legacy:editingteacher
#moodle/legacy:coursecreator
#moodle/legacy:admin
#moodle/site:doanything - special capability, meant for admins, if is set, overrides all other capability settings
#moodle/site:config - applicable in admin/index.php and config.php (might break down later) : 1)admin/config.php 2)admin/configure.php 3)blocks/admin/block_admin.php load_content_for_site()
#moodle/site:readallmessages - reads all messages and history
#moodle/site:approvecourse - approves a pending course
#moodle/site:manageblocks - adding/removing/editing blocks (site, course contexts only for now) : 1)_add_edit_controls moodleblock.class.php
#moodle/site:backup - can create a course backup : 1)course/category.php 2)block_admin.php
#moodle/site:restore - can restore into this context : 1)course/category.php 2)block_admin.php
#moodle/site:import - can import other courses into this context : 1)block_admin.php
#moodle/site:accessallgroups - able to access all groups irrespective of what group the user is in
#moodle/site:accessdb - directly accessing db (phpmyadmin)
#moodle/site:viewfullnames - able to see fullnames of other users
#moodle/site:viewparticipants - able to view participants
#moodle/site:viewreports - able to view site/course reports
#moodle/site:trustcontent - ability to use trusttext feature and bypass cleaning in specific areas
#moodle/site:uploadusers - ability to upload/update users from text file; moodle/role:assign capability is needed for course enrolling
#moodle/blog:view - read blogs (usable in system or course context)
#moodle/blog:create - write new blog posts (usable in system context only)
#moodle/blog:manageofficialtags - create/delete official blog tags that others can use (usable in system context only)
#moodle/blog:managepersonaltags - delete personal blog tags that others can use (usable in system context only) Note: users can always add own personal tags. This setting should be off for students by default.
#moodle/blog:manageentries - edit/delete all blog entries (usable in system context only)
#moodle/course:setcurrentsection - mark course section
#moodle/course:create - create courses : 1)course/edit.php 2)course/category.php 3)course/index.php
#moodle/course:delete - create courses : 1)course/category.php
#moodle/course:update - update course settings
#moodle/course:view - can use this to find participants
#moodle/course:viewparticipants - allows a user to view participant list
#moodle/course:viewscales - view scales (i.e. in a help window?) : 1)course/scales.php
#moodle/course:manageactivities - adding/removing/editing activities and resources (don't think it makes any sense to split these)
#moodle/course:managescales - add, delete, edit scales, move scales up and down : 1)blocks/block_admin.php 2)course/scales.php
#moodle/course:managegroups - managing groups, add, edit, delete : 1)course/groups.php 2)course/group.php
#moodle/course:managefiles - manage course files and folders
#moodle/course:managequestions - manage course questions
#moodle/course:managemetacourse - manage child courses in metacourse
#moodle/course:reset - able to reset the course
#moodle/course:useremail - Can use the enable/disable email stuff
#moodle/course:visibility - hide/show courses : 1)course/category.php
#moodle/course:viewhiddencourses - see hidden courses
#moodle/course:activityvisibility - hide/show activities within a course
#moodle/course:viewhiddenactivities - able to see activities that have been hidden
#moodle/course:sectionvisibility - hide/show sections
#moodle/course:viewhiddensections - view hidden sections
#moodle/course:viewcoursegrades - views all grades in course
#moodle/course:viewhiddenuserfields - view all hidden user fields
#moodle/course:managegrades - manages grades settings in course
#moodle/category:create - create category : 1)course/index.php
#moodle/category:delete - delete category : 1)course/index.php
#moodle/category:update - update category settings (sort and rename) this is currently an admin capability : 1)course/category.php
#moodle/category:visibility - hide/show categories : 1)course/index.php
#moodle/user:viewusergrades - view your own, or other user's grades (with specified context)
#moodle/user:create - create user : 1) user/edit.php
#moodle/user:delete - delete user : 1) admin/user.php
#moodle/user:readuserblogs - read blog entries
#moodle/user:update - update user settings : 1) user/edit.php
#moodle/user:viewdetails - view personally-identifying user details (e.g. name, photo).
#moodle/user:viewhiddendetails - view user details marked as "hidden"
#moodle/calendar:manageownentries - create/edit/delete
#moodle/calendar:manageentries - create/edit/delete
#moodle/role:assign - assign roles to users
#moodle/role:override - can override role capabilities (depending on context)
#moodle/role:manage - create/edit/delete roles, set capability permissions for each role
#moodle/role:unassignself - unassign yourself from your own roles
#moodle/role:viewhiddenassigns - view role assignments that have been marked as hidden
#moodle/question:import - imports questions (course level?) - Yes, question permissions currently need to be course-level.--[[User:Tim Hunt|Tim Hunt]]
#moodle/question:export - exports questions (course level?)
#moodle/question:managecategory - add/delete/edit question categories (course level?)
#moodle/question:manage - add/edit/delete a question (course level)

===User-level Capabilities===
# moodle/user:readuserposts -read individual user posts on profile page (parent?)
# moodle/user:readuserblogs -read individual user blogs on profile page (parent?)
# moodle/user:viewuseractivitiesreport-read individual activity report on profile page (parent?)
# moodle/user:editprofile - edit profile (normally used in CONTEXT_USERID and CONTEXT_SYSTEM)

===Module-level Capabilities===
The capabilities are cached into a database table when a module is installed or updated. Whenever the capability definitions are updated, the module version number should be bumped up so that the database table can be updated.

The naming convention for capabilities that are specific to modules and blocks is 'mod/mod_name:capability'. The part before the colon is the full path to the module in the Moodle code. The module capabilities are defined in mod/mod_name/db/access.php.

#Assignment
##mod/assignment:view- reading the assignment description
##mod/assignment:submit - turn assignment in
##mod/assignment:grade - grading, viewing of list of submitted assignments
#Chat
##mod/chat:chat - allows a user to participate in this chat
##mod/chat:readlog - allows a user to read past chat session logs
##mod/chat:deletelog - allows a user to delete past chat logs
#Choice
##mod/choice:choose - make a choice
##mod/choice:readresponses - read all responses
##mod/choice:deleteresponses - deletes all responses
##mod/choice:downloadresponses - download responses
#Database
##mod/data:viewentry - reads other people's entry
##mod/data:writeentry - add / edit and delete (own) entries
##mod/data:managetemplates - add, delete, edit fields and templates
##mod/data:manageentries - edit/delete all entries
##mod/data:comment - comment
##mod/data:managecomments - edit/delete all comments
##mod/data:rate - rate an entry
##mod/data:viewrating
##mod/data:approve - approves an entry
##mod/data:uploadentries - batch upload of entries
#Exercise
##mod/exercise:assess
#Forum
##mod/forum:viewdiscussion
##mod/forum:viewdiscussionsfromallgroups
##mod/forum:viewhiddentimedposts
##mod/forum:startdiscussion
##mod/forum:replypost
##mod/forum:viewrating
##mod/forum:viewanyrating
##mod/forum:rate
##mod/forum:createattachment
##mod/forum:deleteownpost
##mod/forum:deleteanypost
##mod/forum:splitdiscussions
##mod/forum:movediscussions
##mod/forum:editanypost
##mod/forum:viewqandawithoutposting
##mod/forum:viewsubscribers
##mod/forum:managesubscriptions
##mod/forum:throttlingapplies
#Glossary
##mod/glossary:write - add entries
##mod/glossary:manageentries - add, edit, delete entries
##mod/glossary:managecategories - create, delete, edit categories
##mod/glossary:comment - comment on an entry
##mod/glossary:managecomments - edit, delete comments
##mod/glossary:import - import glossaries
##mod/glossary:export - export glossaries
##mod/glossary:approve - approve glossaries
##mod/glossary:rate - rates glossary
##mod/glossary:viewrating - view ratings
#Hotpot
##mod/hotpot:attempt - attempt a hotpot
##mod/hotpot:viewreport - review and view reports
##mod/hotpot:grade - (grade? and) regrade
##mod/hotpot:deleteattempt - deletes attempts
#Label
##none
#Lams
##mod/lams:participate - original student
##mod/lams:manage - original teacher
#Lesson
##mod/lesson:edit - add and edit pages
##mod/lesson:manage - view student attempts
#Quiz
##mod/quiz:grade - comment, override grade, manual grade
##mod/quiz:preview - previews the quiz
##mod/quiz:viewreports - view quiz result reports
##mod/quiz:manage - add/delete/move (up or down) questions for a quiz
##mod/quiz:attempt - attempt the quiz--[[User:Tim Hunt|Tim Hunt]]
#Resource
#Scorm
##mod/scorm:viewgrades
#Survey
##mod/survey:download - downloads survery result
##mod/survey:participate - participate/ do survey
##mod/survey:readresponses - read all user's responese
#Wiki
##mod/wiki:participate - original student, meaning depends of type and course setting
##mod/wiki:manage - original teacher, manages assigned group; moodle/site:accessallgroups is needed to manage all groups
##(Waiting on new wiki)
#Workshop
##mod/workshop:participate - original student, allows user to submit and assess
##mod/workshop:manage - original teacher, user can manage others
##(Waiting on new Workshop)

===Enrolment-level Capabilities===

The naming convention for capabilities that are specific to enrolment is 'enrol/enrol_name:capability'. The enrolment capabilities are defined in enrol/enrol_name/db/access.php.

#Authorize.net Payment Gateway
##enrol/authorize:managepayments - manage user payments, capture, void, refund, delete etc.

===Blocks===
#activity_modules
##None
#admin
#admin_2
#admin_bookmarks
#blog_menu
#blog_tags
#calendar_month
#calendar_upcoming
#course_list
#course_summary
#glossary_random
#html
#loancalc
#login
#messages
#news_items
#online_users
#participants
#quiz_results
#recent_activity
#rss_client
##block/rss_client:createprivatefeeds
##block/rss_client:createsharedfeeds
##block/rss_client:manageownfeeds
##block/rss_client:manageanyfeeds
#search
#search_forums
#section_links
#site_main_menu
#social_activities

===Questions===
I am adding question categories here because they seem to have been forgotten in the whole scheme of things since having been removed from the quiz module itself. I've made a suggestion on how these could be handled in MDL-6118.

: See [http://moodle.org/mod/forum/discuss.php?d=51143 this forum thread] for a discussion about the current problems wth publishing question categories.[[User:Tim Hunt|Tim Hunt]] 18:50, 8 August 2006 (WST)

==Programming Interface==

Although the Roles system may look complicated at first glance, implementing it in Moodle code is fairly simple.

* You need to define each capability once, so that Moodle can upgrade existing roles to take advantage of it. You do this in an '''access.php''' inside the ''db folder'' of any module (eg see mod/forum/db/access.php). The array contains entries like this (note the descriptions for the legacy roles which provides forward compatibility):

<code php>
'mod/forum:viewforum' => array(
'captype' => 'read',
'contextlevel' => CONTEXT_MODULE,
'archetypes' => array(
'guest' => CAP_PREVENT,
'student' => CAP_ALLOW,
'teacher' => CAP_ALLOW,
'editingteacher' => CAP_ALLOW,
'coursecreator' => CAP_ALLOW,
'manager' => CAP_ALLOW
)
),
</code>

* To load/change these capabilities you need to bump the module version. There's no need to provide changes or differences as Moodle will scan the whole array and sort it out.
* On each page you need to find the context the user is working in, using the '''get_context_instance()''' function. For example, in the forum module:

<code php>
$context = get_context_instance(CONTEXT_MODULE, $cm->id);
</code>

* or at the course level:

<code php>
$context = get_context_instance(CONTEXT_COURSE, $id);
</code>

* Then, whenever you want to check that the current user has rights to do something, call '''has_capability()''' like this:

<code php>
if (!has_capability('mod/forum:viewforum', $context)) {
print_error('nopermissiontoviewforum');
}
</code>

* If you just want to assert a capability and then finish with an error message if it's not met (as we did above), then a shorter way it to use '''require_capability()''' like this:

<code php>
require_capability('mod/forum:viewforum', $context);
</code>

* Note that there are extra parameters you can specify to get a custom error message, otherwise users get an automated "No permissions" message that lists the permission they were missing.

As a result of the new Roles System, all calls to isadmin(), iscoursecreator, isteacheredit(), isteacher(), isstudent(), and isguest() will have to be replaced with calls to has_capability() or require_capability(). However, these functions will be retained for some backward compatibility with old code, using the legacy capabilities to try and work out what to do.

==Problem areas we are working on ==

===Student view===

The "Student view" button has been removed completely.

If there is time and a secure way can be found, it will be replaced by a menu to let the user assume a temporary role in the context of that course.

===Teacher forum===

Teacher forums were always a curious exception to normal forums, as they were not part of a course as such, and were not backed up.

We're taking the opportunity to rectify this. The upgrade converts teacher forums with content to normal forums in section 0 of the course, and ensures that only teachers can access them. If the teacher forum had not been used in the course then it's not converted and will just dissappear.

===Enrolment plugins===

====Process of logging in====

# load_user_capability() is called to load all the capabilities
# check_enrolment_plugins() is called at the top of load_user_capability() to check all the enrolment plugins.
# For each active plugin:
##Check for setup_enrolments($user) and run it. This function will do all the processing needed to assign or unassign roles from the current user.
# load_user_capability() continues and loads up all the roles
# load_defaultuser_role() is called to add default site permissions (all users)

====Process of checking access to a course====

require_login($course->id) is called by the script and has logic like this:

# Is the user a guest at site level?
## Yes: Does the course allow guests?
### Yes: return true (and further capabilities are checked by the script)
### No: send the user to course/enrol.php for enrolment
## No: continue below

# Does the user have moodle/course:view in that (course) context?
## Yes: then they can enter (and further capabilities are checked by the script)
## No: is guest access allowed on the course?
### Yes: assign temporary guest role to that user for that context (in session cache).
### No: send the user to course/enrol.php for enrolment.

====Process of enrolling====

(more soon)

==Scenario brainstorming==

This section is for brainstorming some example roles that we would like to support. Note some of these *may* not be possible in 1.7.

===Student===
Obviously.

===Site Designers===
Is there a role for people involved in how the site looks but not full administrators? Thinking here of online control of themes rather than FTP theme uploading. But in either case they caneditlogos, caneditcss, candeditlevelatwhichthemeapplies.

===Educational Authority Adviser===
Someone who would want to browse the site and may be asked to comment or contribute to particular discussions or developments in school. Access for this role would be controlled by the school in the case of school level moodles but may be different if there were to be a Local Authority wide Moodle.

===Educational Inspector===
Someone who will visit the site to verify the school's self review that comments on home school relationships, extending the classroom etc. They may want to see summaries of usage and reports from surveys garnering parent and pupil views.

===Second Marker / Moderator===
A teacher within ths site that has access to assignments and quizzes from another teacher's course for second marking purposes. This may need additional functionality adding to the assignment module so that two sets of grades/feedback can be given to one set of assignments.

===Peer observer of teaching===
Many institutions encourage peer observation of teaching, to encourage reflection on practice. In online environments this will be similar to moderation or inspection. The peer observer would need to be able to experience the course "as a student", but also to be able to view summaries of usage, transcripts of interactions (forums/surveys/polls etc), grades assigned (e.g. in assignments).

===External Examiner===
Has all the rights of inspectors, but would also need to be able to review assignments and feedback, view forums, glossaries etc. However, would not want to post, feedback onto the site at all.

===Parent===
A parent will have one or more children in one or more institutions which could be using one or more moodle instances or a mixture of Learning Platforms. A parent's role will vary depending on the age of their children and whether they are contributing as a parent or a school supporter.

In Early Years (EY=3+4 yr olds) and Key Stage 1 (KS1=5+6 yr olds) they may play/learn on an activity or write for the child. Parents often interpret homework tasks and read to their children perhaps filling in a joint reading diary. In Key Stage 2 (KS2=7-11 yr olds) parents would be more monitoring but may join in as well.

In Key stages 3 (KS3=12-14 yr olds) and 4 (KS4=15+16 yr olds) this changes to more of a monitoring/awareness role where a parent would expect to have a summary report of attendance, attainment and general achievement on a weekly/monthly/termly or annual basis. Parents will often be asked to sign and write back comments about this review report.

In all Key Stages there is a great need for parents to receive communication from the school which they can confirm they have received by signing a form. In some cases this may also involve making choices from a list. It may also involve payment for a trip or disco being returned so there could be the possibility of electronic payments. Also in all Key Satges there may be a home-school agreement which may be signed up to. Could this form part of a site policy system that incorporates a tickable list of activities the parent agrees to the child using (blogs/wikis/forums etc.)?

Parent's evenings often involve complex booking systems that attempt to get parent's and teachers together. Easy for EY/KS1/KS2 very difficult for KS3/KS4. Wow would this help if it was built into the Learning Platform.

In some cases there needs to be confidential communication between the parent and the teacher without the child being party to this. It may involve teaching and learning but could also involve a behaviour or medical issue. Often this may be done via a sealed letter or face to face.

The latest incarnation of OfSTED with the Self Review Framework (SEF) there is a greater emphasis on schools gathering parent voice via surveys and discussion. There is a clear match here with parents have access to parental votes, questionnaires and discussions and for schools to be able to publish news, results and reports back to parents.

In the UK the LP framework and agenda as being pushed by the DfES via Becta emphasises that within the mandatory groups and roles functionality the parent role is likely to be required to meet the LP Framework procurement standard.

Again in the UK, parents have their own independent right of access to a child's educational records. Obviously, children's records must not be made available to other parties, including the parents of other children in the same class. Thus it would be necessary to associate parent accounts with their own child's accounts in such a way that they could, if so desired, have read access to their child's grades, answers and contributions, but generally not those of other children - this may be problematic in the case of wiki activities or forum posts.

There is some concern that children's forum contributions etc may be constrained if their parents are able to read all that they write; this may be particularly problematic in areas such as Personal, Social and Health Education (PSHE), where some schools may choose to use obfuscated usernames.

===Manager===
''Typically, for a manager in a business environment, they will want to be able to view reports, view grades for Quizzes, and view results from Surveys/Questionnaires for specific courses. They will also want to be able to view the list of enrolled students.''

Note that in Moodle 2.0, there is a manager role, but that is manager like a lesser admin. It is not manager like a manager in a business environment.

===Weekly Seminar Leader===
''In a university seminar, typically 8-15 students in their 3rd/4th year, each student is responsible for leading one topic in a study series. I ask each student to research 5-10 resources, then give a powerpoint presentation to the other students. This is followed by an in-class discussion and then online homework. The homework involves some fun quiz questions and then some reflective journal questions. I ask each seminar leader to prepare the quiz questions and journal questions as well as their presentation. To do that, I would like to assign activity-making/authoring roles to the student--either for a short period, or for duration of the whole course. Thus "Allow Quiz Authoring Role" or "Allow Assignment Authoring Role" at the course level or, if possible, even the Topic level (in a topic or week format course) would be important.''

===Mentor/Mentee===
''Please add text here...''

===Community-Designed Rating Criteria===
''The gradebook tends to be the domain of the teacher. What if community/peer ratings/marks could also be entered there? What if peer assessment criteria could be designed by the students, not just the teacher?''

===Visitor===

This would be a role whereby one could allow a visitor to visit one's classroom. This might be a colleague interested in seeing your course, or a journalist who might be writing an article about one's site. They should not be able to see the names of any students anywhere (eg recent activity, forum posts) for privacy reasons. They should be able to try out things like quizzes, and lessons but no grades would be recorded (like in teacher preview mode). They would not be able to participate in choices and forums but could view them. It would be read only in a way like former-student role below but without access to a particular student's records that former student role would grant.

===Guest Speaker===

This role would be similar to the Visitor role above, but would allow seeing student names, and also allow both reading and posting to a specific forum or forums. We often have "guest speakers" who read and respond to student forum posts. Right now we have to add them as students, which isn't ideal.

===Former Student===
This role would be of particular use for courses with rolling enrollments. This role would be one where a student had completed all of the requirements of a course (ie. assignments, quizzes etc.) but wished to have continued access to the course material for review or consultation. The key factor is that one would give access to the completed student to the notes he read, his work and the teacher's comments on it, but he would not be allowed to do anything that would take up the teacher's time. In other words, a sort-of read-only access to the course. How forums, which might contain pertinent information and would continue to grow, would be handled is a question. Perhaps the student would be shown only what was in the forums at the time he completed the course. He would not be allowed to see any new posts or add any himself. Same thing for database and glossary entries. In other words, a snapshot of the course at the time his regular enrollment ended. He shouldn't be able to see the names or profiles of any newly enrolled students for privacy reasons-hence the restrictions on forum access. One issue that would have to be dealt with would be changes to existing modules-such as resources. Does the student get access to the module as it was or as it is? We have no versioning of resources in Moodle so this would be a problem. What about a teacher changing a quiz question so that the answer is different? What would a former student see?

===Alumnus===
An ALUMNUS should be able to search for all other ALUMNI of the school, interact with them and be enrolled in a separate course - which is like a META course with all the content of his learning and interaction - as well as capabilities to be a part of this ALUMNI only course. All the teachers of courses during school years should automatically be a part of the ALUMNI course .. which means when an ALUMNUS is enrolled in a course, the original teachers of all his courses get enrolled ? --[[User:Anil Sharma|Anil Sharma]] 20:54, 15 July 2006 (WST)

===Librarian===

Reference Librarians have an active role in most of the courses taught at some schools such as Earlham College (with Bibliographic Instruction). The Librarian role within Moodle could encompass default read access to all courses (unless prohibited by course teacher) and read access to all components of the course unless access is barred (again by teacher). The Librarians would also perhaps have a block called perhaps Reference Services or Reference Desk with write access where they could deposit resources. Also this block might have a chat applet whereby enrolled students could chat to the Reference Librarian on duty about their bibliographic research needs.

In schools there is often a book review system. This may be covered by the lending system database but may not in which case a librarian may neeed to have a course area they can create a database template to handle the reviews in which case they may have a normal teacher style role? Off topic but course an integration with common schools database systems would be great.

===Teacher===

Teachers should have read access to other Teacher's courses unless explictly prohibited. They should be able to set parts of their own course to be totally private (perhaps even to admin?). Just as each activity can currently be set to have group access, each activity could have a permissions field. Teachers could set default permissions for all activities on their course (eg they might disallow Librarian access for example) and then change the access permission for an individual activity.

I think that what is needed is a simple heirarchy of permissions and levels of granularity.

I would take issue with "teachers should have read access to other teacher's courses unless explicitly prohibited." This is a violation of the students' privacy as how they perform and what they do in one class isn't the business of another teacher. Moreover, in the real world a teacher wouldn't suddenly go sit in on a colleague's class without asking permission first. I would not have appreciated such an invasion of privacy as either a teacher or a student. It could be an option, but shouldn't be default.--[[User:N Hansen|N Hansen]] 19:54, 12 June 2006 (WST)

===Community Education Tutors/Trainers===
Teachers may be community adult education trainers making use of a school moodle so must only have access to their courses unless given access elsewhere. They would not necessarily get the default teacher privileges.

===Secretary/Student Worker===

We often have faculty who want their departmental secretary or student worker to scan and upload files and perhaps create resources. Currently they have to be given teacher access to the course. This is dangerous from a FERPA standpoint since they could easily get access to grades.

===Teaching Assistant===

Our Faculty frequently have undergraduate students acting as Teaching Assistants. These students need to be able to add resources, create assignments, and possibly grade assignments. However, due to FERPA they cannot have access to other students' overall grade information. I think the requirements here are slightly different than those of Secretary/Student Worker

===Student - FERPA rights===

A student that has asserted their FERPA rights to non-disclosure. Typically includes not publishing their name
in any public place. Could include this student only being seen with an "alias" within course spaces. Is this an attribute rather
than a role?

===Help Desk===

Help desk agents that have read access for the purposes of trouble shooting. Some care in placing this role within a hierarchy
of inheritance is needed, full access will be problematic with FERPA.

===Admin - Catgory based===

Basically a person in between full Admin and Creator that has the permissions of an Admin but only with respect to courses and students. Currently a Creator has permissions site-wide which does not always meet the requirements of a given organisation (e.g. Department A may not be happy that a person from Department B can create/modify courses within Department A's area). The ability to designate a Creator within a specific category would allow areas to be set up for a faculty/department/organisation and allow the Admin for that area to create/delete courses, upload users, add site-wide entries to the calendar etc.

===Process Roles===

organising the learning process for a group you wish to have the choice to place students in differnt roles: examples of this are:
* Give a student the role of forum-moderator with edit and chunk-rights
* Give students different roles & rights in a Webquest design (and change these roles next week
* Give students different resources, depending of their roles in a rolegame/simulation
* Give a student the rights to create the section content of next week (and only that week..)

==See also==

*[[Hardening new Roles system]]
*[[Roles and modules]]
*Using Moodle course:
**[http://moodle.org/mod/forum/view.php?f=941 Roles and Capabilities forum]
**Key discussions at Using Moodle forums:
***[http://moodle.org/mod/forum/discuss.php?d=38788 Roles and Permissions architecture]
***[http://moodle.org/mod/forum/discuss.php?d=56302#256313 An example of admin roles as set in the database]
*** A short description by Tim Hunt of some new role related features in Moodle 2.0: [http://moodle.org/mod/forum/discuss.php?d=139641&parent=610871 Adding new roles as part of a module]

[[Category:Roles]]
[[Category:Interfaces]]

User:Abhijit m

2016-03-27T08:21:18Z

Abhijit13: Created page with "Abhijit A.M. http://github.com/abhijit13/"

Abhijit A.M.
http://github.com/abhijit13/

Output API

2016-03-27T08:19:18Z

Abhijit13:

{{Template:Work in progress}}

{{ Moodle 2.9 }}

See [[ Output Components ]] for (much) older information on the using output components in previous versions of Moodle.

This page is a fresh attempt to explain how renderers, renderables, themes and templates all work together for Moodle 2.9.

Lets start with building a page that is part of an admin tool.

E.g.
/admin/tool/demo/index.php
<code php>
<?php
// Standard GPL and phpdocs
require_once(__DIR__ . '/../../../config.php');
require_once($CFG->libdir.'/adminlib.php');

admin_externalpage_setup('tooldemo');

// Set up the page.
$title = get_string('pluginname', 'tool_demo');
$pagetitle = $title;
$url = new moodle_url("/admin/tool/demo/index.php");
$PAGE->set_url($url);
$PAGE->set_title($title);
$PAGE->set_heading($title);

$output = $PAGE->get_renderer('tool_demo');

echo $output->header();
echo $output->heading($pagetitle);

$renderable = new \tool_demo\output\index_page('Some text');
echo $output->render($renderable);

echo $output->footer();
?>
</code>

Explaining this demo step by step we have firstly the standard config and includes, plus the admin_externalpage_setup('tooldemo') which calls require_login and performs permissions checks for admin pages.
<code php>

// Standard GPL and phpdocs
require_once(__DIR__ . '/../../../config.php');
require_once($CFG->libdir.'/adminlib.php');

admin_externalpage_setup('tooldemo');
</code>

Then we load the title of the page from a lang string (see [[String_API]] ). We use this string to set some $PAGE properties (url title and heading).
<code php>

// Set up the page.
$title = get_string('pluginname', 'tool_demo');
$pagetitle = $title;
$url = new moodle_url("/admin/tool/demo/index.php");
$PAGE->set_url($url);
$PAGE->set_title($title);
$PAGE->set_heading($title);
</code>

What is $PAGE and where did it come from ?

$PAGE is a global variable used to track the state of the page that is being returned. It is an instance of the moodle_page class defined in lib/pagelib.php. See [[Page_API]] for more information on the $PAGE variable.

The most important properties stored in $PAGE are the page context, the url, the layout, title and headings. $PAGE also gives access to some other important classes such as $PAGE->requires, which is an instance of the page_requirements_manager (lib/outputrequirementslib.php). The page_requirements_manager class lets us set dependencies on e.g. javascript and css to be inserted in the correct place in the page (The order things are inserted in the page is hugely important for performance).

$PAGE also lets us load specific renderers for a plugin, or plugin and subtype. We will cover renderers in more detail next.

<code php>
$output = $PAGE->get_renderer('tool_demo');

</code>

This gets an instance of the plugin_renderer_base class that we use to create all output for our page. Themers can subclass this renderer to override specific render methods in order to customise Moodle's output. See [[Output_renderers]] for more information, and [[Overriding_a_renderer]] for information about how themers can customise a renderer.

Note - some pages use the global variable $OUTPUT to generate their output. This is a generic renderer used for core pages etc, but plugins should always use a more specific plugin renderer.

<code php>
echo $output->header();
echo $output->heading($pagetitle);
</code>

This code prints the header of the page and adds one heading to the page at the top of the content region. Page headings are very important in Moodle and should be applied consistently. See [[HTML_Guidelines]] for more information on how and where to use headings.

<code php>
$renderable = new \tool_demo\output\index_page('Some text');
echo $output->render($renderable);
</code>

This is the most interesting part of our page. We are creating a renderable and telling our renderer to render it. The renderable is usually more complex than this, it should hold all the data required for the renderer to display the page. This means we should perform all our logic such as database queries, page parameters and access checks in advance and the results should be passed as data to the renderable. The renderable then just takes that data and returns a HTML representation of it.

<code php>
echo $output->footer();
</code>

This prints the HTML for the bottom of the page. It is very important because it also prints out things that were added to the page_requirements_manager and need to be printed in the footer. Things like javascript includes, navigation tree setup, closing open containers tags etc. The reason all javascripts are added to the footer of the page is for performance. If you add javascript includes to the top of the page, or inline with the content the browser must stop and execute the javascript before it can render the page. See https://developers.google.com/speed/docs/insights/BlockingJS for more information.

In the code above, we created a renderable. This is a class that you have to add to your plugin. It holds all the data required to display something on the page. Here is the renderable for this example:

/admin/tool/demo/classes/output/index_page.php
<code php>
<?php
// Standard GPL and phpdocs
namespace tool_demo\output;

use renderable;
use renderer_base;
use templatable;
use stdClass;

class index_page implements renderable, templatable {
/** @var string $sometext Some text to show how to pass data to a template. */
var $sometext = null;

public function __construct($sometext) {
$this->sometext = $sometext;
}

/**
* Export this data so it can be used as the context for a mustache template.
*
* @return stdClass
*/
public function export_for_template(renderer_base $output) {
$data = new stdClass();
$data->sometext = $this->sometext;
return $data;
}
}
?>
</code>

This class implements the renderable interface, which has no methods, and the templatable interface, which means that this class could be rendered with a template, so it must implement the "export_for_template" method. So in this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else fancy with the data in this example (but it could). Note that the export_for_template function should only return simple types (arrays, stdClass, bool, int, float, string).

Now lets look at the renderer for this plugin.

tool/admin/demo/classes/output/renderer.php
<code php>
<?php
// Standard GPL and phpdocs
namespace tool_demo\output;

defined('MOODLE_INTERNAL') || die;

use plugin_renderer_base;

class renderer extends plugin_renderer_base {
/**
* Defer to template.
*
* @param index_page $page
*
* @return string html for the page
*/
public function render_index_page($page) {
$data = $page->export_for_template($this);
return parent::render_from_template('tool_demo/index_page', $data);
}
}
?>
</code>

The renderer exists to provide render_x methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (render_index_page) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A themer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated html) to customize the output.

The template used in this plugin is located in the plugins templates folder. The template can also be overridden by a themer.

admin/tool/demo/templates/index_page.mustache
<code xml>
<div class="hero-unit">
<h1>Heading</h1>
<p>{{sometext}}</p>
</div>
</code>

This is the mustache template for this demo. It uses some bootstrap classes directly to position and style the content on the page. {{sometext}} is replaced with the variable from the context when this template is rendered. For more information on templates see [[Templates]].

Output API

2016-03-27T08:17:10Z

Abhijit13: added <?php ?> so that the page code can be directed copy-pasted in a file

{{Template:Work in progress}}

{{ Moodle 2.9 }}

See [[ Output Components ]] for (much) older information on the using output components in previous versions of Moodle.

This page is a fresh attempt to explain how renderers, renderables, themes and templates all work together for Moodle 2.9.

Lets start with building a page that is part of an admin tool.

E.g.
/admin/tool/demo/index.php
<code php>
<?php
// Standard GPL and phpdocs
require_once(__DIR__ . '/../../../config.php');
require_once($CFG->libdir.'/adminlib.php');

admin_externalpage_setup('tooldemo');

// Set up the page.
$title = get_string('pluginname', 'tool_demo');
$pagetitle = $title;
$url = new moodle_url("/admin/tool/demo/index.php");
$PAGE->set_url($url);
$PAGE->set_title($title);
$PAGE->set_heading($title);

$output = $PAGE->get_renderer('tool_demo');

echo $output->header();
echo $output->heading($pagetitle);

$renderable = new \tool_demo\output\index_page('Some text');
echo $output->render($renderable);

echo $output->footer();
?>
</code>

Explaining this demo step by step we have firstly the standard config and includes, plus the admin_externalpage_setup('tooldemo') which calls require_login and performs permissions checks for admin pages.
<code php>

// Standard GPL and phpdocs
require_once(__DIR__ . '/../../../config.php');
require_once($CFG->libdir.'/adminlib.php');

admin_externalpage_setup('tooldemo');
</code>

Then we load the title of the page from a lang string (see [[String_API]] ). We use this string to set some $PAGE properties (url title and heading).
<code php>

// Set up the page.
$title = get_string('pluginname', 'tool_demo');
$pagetitle = $title;
$url = new moodle_url("/admin/tool/demo/index.php");
$PAGE->set_url($url);
$PAGE->set_title($title);
$PAGE->set_heading($title);
</code>

What is $PAGE and where did it come from ?

$PAGE is a global variable used to track the state of the page that is being returned. It is an instance of the moodle_page class defined in lib/pagelib.php. See [[Page_API]] for more information on the $PAGE variable.

The most important properties stored in $PAGE are the page context, the url, the layout, title and headings. $PAGE also gives access to some other important classes such as $PAGE->requires, which is an instance of the page_requirements_manager (lib/outputrequirementslib.php). The page_requirements_manager class lets us set dependencies on e.g. javascript and css to be inserted in the correct place in the page (The order things are inserted in the page is hugely important for performance).

$PAGE also lets us load specific renderers for a plugin, or plugin and subtype. We will cover renderers in more detail next.

<code php>
$output = $PAGE->get_renderer('tool_demo');

</code>

This gets an instance of the plugin_renderer_base class that we use to create all output for our page. Themers can subclass this renderer to override specific render methods in order to customise Moodle's output. See [[Output_renderers]] for more information, and [[Overriding_a_renderer]] for information about how themers can customise a renderer.

Note - some pages use the global variable $OUTPUT to generate their output. This is a generic renderer used for core pages etc, but plugins should always use a more specific plugin renderer.

<code php>
echo $output->header();
echo $output->heading($pagetitle);
</code>

This code prints the header of the page and adds one heading to the page at the top of the content region. Page headings are very important in Moodle and should be applied consistently. See [[HTML_Guidelines]] for more information on how and where to use headings.

<code php>
$renderable = new \tool_demo\output\index_page('Some text');
echo $output->render($renderable);
</code>

This is the most interesting part of our page. We are creating a renderable and telling our renderer to render it. The renderable is usually more complex than this, it should hold all the data required for the renderer to display the page. This means we should perform all our logic such as database queries, page parameters and access checks in advance and the results should be passed as data to the renderable. The renderable then just takes that data and returns a HTML representation of it.

<code php>
echo $output->footer();
</code>

This prints the HTML for the bottom of the page. It is very important because it also prints out things that were added to the page_requirements_manager and need to be printed in the footer. Things like javascript includes, navigation tree setup, closing open containers tags etc. The reason all javascripts are added to the footer of the page is for performance. If you add javascript includes to the top of the page, or inline with the content the browser must stop and execute the javascript before it can render the page. See https://developers.google.com/speed/docs/insights/BlockingJS for more information.

In the code above, we created a renderable. This is a class that you have to add to your plugin. It holds all the data required to display something on the page. Here is the renderable for this example:

/admin/tool/demo/classes/output/index_page.php
<code php>
// Standard GPL and phpdocs
namespace tool_demo\output;

use renderable;
use renderer_base;
use templatable;
use stdClass;

class index_page implements renderable, templatable {
/** @var string $sometext Some text to show how to pass data to a template. */
var $sometext = null;

public function __construct($sometext) {
$this->sometext = $sometext;
}

/**
* Export this data so it can be used as the context for a mustache template.
*
* @return stdClass
*/
public function export_for_template(renderer_base $output) {
$data = new stdClass();
$data->sometext = $this->sometext;
return $data;
}
}
</code>

This class implements the renderable interface, which has no methods, and the templatable interface, which means that this class could be rendered with a template, so it must implement the "export_for_template" method. So in this example, the class accepts data via it's constructor, and stores that data in class variables. It does nothing else fancy with the data in this example (but it could). Note that the export_for_template function should only return simple types (arrays, stdClass, bool, int, float, string).

Now lets look at the renderer for this plugin.

tool/admin/demo/classes/output/renderer.php
<code php>
// Standard GPL and phpdocs
namespace tool_demo\output;

defined('MOODLE_INTERNAL') || die;

use plugin_renderer_base;

class renderer extends plugin_renderer_base {
/**
* Defer to template.
*
* @param index_page $page
*
* @return string html for the page
*/
public function render_index_page($page) {
$data = $page->export_for_template($this);
return parent::render_from_template('tool_demo/index_page', $data);
}
}
</code>

The renderer exists to provide render_x methods for all renderables used in the plugin. A theme designer can provide a custom version of this renderer that changes the behaviour of any of the render methods and so to customize their theme. In this example, the render method for the index page (render_index_page) does 2 things. It asks the renderable to export it's data so that it is suitable for passing as the context to a template, and then renders a specific template with this context. A themer could either manipulate the data in the render method (e.g. removing menu entries), or change the template (change the generated html) to customize the output.

The template used in this plugin is located in the plugins templates folder. The template can also be overridden by a themer.

admin/tool/demo/templates/index_page.mustache
<code xml>
<div class="hero-unit">
<h1>Heading</h1>
<p>{{sometext}}</p>
</div>
</code>

This is the mustache template for this demo. It uses some bootstrap classes directly to position and style the content on the page. {{sometext}} is replaced with the variable from the context when this template is rendered. For more information on templates see [[Templates]].