Documentation update

doc.php

@@ -6,6 +6,7 @@ require_once($CFG->libdir.'/weblib.php');
 $systemcontext = context_system::instance();
 
 $PAGE->set_url("/local/treestudyplan/doc.php",array());
+$PAGE->requires->css(new moodle_url($CFG->wwwroot.'/local/treestudyplan/css/devstyles.css'));
 $PAGE->set_pagelayout('base');
 $PAGE->set_context($systemcontext);
 require_login();

doc/advanced.htm

@@ -44,7 +44,7 @@
             <li>Display a <b>custom course field</b></li>
         </ol>
         <p>Go to <b>Site administration</b> -> <b>Courses</b> -> <b>Studyplans</b> -> <b>Studyplan settings</b><br>
-        Under <b>Course display name</b> you can select if you want to use <i>shortname</i>, <i>ID field</i> or any other previously configured custom field</p>
+        Under <b>Course display name</b> you can select if you want to use <i>shortname</i>, <i>ID field</i> or any other previously configured custom course field</p>
     </p>
 
     <h2>Grade & Scale interpretation</h2>
@@ -63,4 +63,82 @@
     <p>While scales are automatically added and cannot be removed, you can remove previously configured <i>maximum grade points</i>. 
         To do so, check the <b>delete</b> mark next to it, and press <b>save</b> </p>
 
+    <h2>Accessing studyplans in context</h2>
+    <p>The studyplan plugin is category context aware - meaning that every studyplan is placed in a context. And users can have rights to view and/or edit 
+        studyplans within a specific context. </p>
+    <p>To edit a studyplan in a specific context, you can use one or two ways:</p>
+    <ol>
+        <li>Go to the category you want to. If you have studyplan view or edit rights (Right <i>local/treestudyplan:editstudyplan</i>), you will find a link <b>Manage study plans</b> in that category's menu. </li>
+        <li>Go to <b>manage study plans</b> in the primary navigation, and select the context you need in the drop down menu in the top left. This drop down menu will
+        only show the category contexts you have studyplan management access to (Right <i>local/treestudyplan:editstudyplan</i>) </li>
+    </ol>
+    <p>The list in the top left of the management page, also shows you how many study plans there are in the contexts listed. Since subcategories are also listed, this can be
+        very useful for management purposes.</p>
+    <img src="img/Contexts-Manage.png" class="border border-primary rounded-lg ml-3">
+
+    <h3>Viewing student studyplans</h3>
+    <p> Viewing the studyplans of students is also a right that is context-aware. (Right <i>local/treestudyplan:viewuserreports</i>)</p>
+    <p> Both methods outlined above also work for viewing student studyplans. The main difference is that the drop-down list on the top-left of the page
+        only shows the categories that actually have studyplans that are viewable for the current user. (Which means that the user can not only see the study plan
+        itself, but also the results of specific users). It is recommended to give this right to all teachers in a specific category, unless you have specific reasons 
+        why teachers might not be allowed to see all results of the students.
+    </p>
+    <img src="img/Contexts-View.png" class="border border-primary rounded-lg ml-3">
+
+    <h2>Block MyStudyplan</h2>
+    <p>Using the block <i>My Studyplan</i> you can show students the studyplans they are enrolled in on the dashboard page. This may be useful for navigation.</p>
+    <p>This block shows <i>teachers</i> another view - namely all studyplans they are currently teaching courses in (orderd in tabs). For teachers, this view will often take a 
+        few seconds to load, especialy if they teach in multiple study plans, since the result statistics for each course are collected each time</p>
+    <p>In spite of the loading time, this view can be beneficial to teachers, since it can easily show them the statistics for the courses they are teaching</p>
+
+    <a id="rights"><h2>Roles and permissions</h2></a>
+    <p>For the studyplan the following permissions are defined:</p>
+    <table>
+        <tr>
+            <th>Right</th>
+            <th>Explanation</th>
+            <th>Default applied to</th>
+            <th>Context applicabble</th>
+        </tr>
+        <tr>
+            <td>local/treestudyplan:editstudyplan</td>
+            <td></td>
+            <td>manager</td>
+            <td>System and/or category</td>
+        </tr>
+        <tr>
+            <td>local/treestudyplan:forcescales</td>
+            <td>Allow studyplan managers with this right to push scales for grading to all selected grable activities (see above)<br>
+                (Effective only when Manual aggregation method is selected in the study plan)</td>
+            <td>manager</td>
+            <td>System and/or category</td>
+        </tr>
+        <tr>
+            <td>local/treestudyplan:selectowngradables</td>
+            <td>Teachers with this right in a course context, can select their own gradable activities in the plan<br>
+                (Effective only when Manual aggregation method is selected in the study plan)</td>
+            <td>teacher</td>
+            <td>Course</td>
+        </tr>
+        <tr>
+            <td>local/treestudyplan:configure</td>
+            <td>Users with this right can configure global interpretation of scales and point grades </td>
+            <td>manager</td>
+            <td>System</td>
+        </tr>
+        <tr>
+            <td>local/treestudyplan:viewuserreports</td>
+            <td></td>
+            <td>manager</td>
+            <td>System and/or category</td>
+        </tr>  
+    </table>
+
+    <p>While the studyplan management rights are added by default to the <b>manager</b> role, the right to just view the studyplans for teachers and students is not 
+       added to any default role. You should make a separate role for faculty that is allowed to view the study plans (or integrate it in an existing role),
+       grant the roght <i>local/treestudyplan:viewuserreports</i> to that role, and assign the role to all users that should have this right in a given context.</p>
+
+    
+
+
 </div>

doc/index.htm

@@ -30,9 +30,15 @@ Study plans|/local/treestudyplan/view-plan.php||en
 Manage Study plans|/local/treestudyplan/edit-plan.php||en
     </pre></p>
     <p> The studyplan plugin wil automatically hide the primary navigation items that are not applicable for the current user.</p>
-    <a id="setup"><h2>Configuration</h2></a>
+    <h2>Roles post install</h2>
-    After installing the plugin you can find the main configuration in <b>Site administration</b> -> <b>Courses</b> -> <b>Studyplans</b>
+    <p>While the studyplan management rights are added by default to the <b>manager</b> role, the right to just view the studyplans for teachers and students is not 
-    <br>
+        added to any default role. You should make a separate role for faculty that is allowed to view the study plans (or integrate it in an existing role),
-    <img src="img/Siteconfig.png" class="border border-primary rounded-lg ml-3">
+        grant the roght <i>local/treestudyplan:viewuserreports</i> to that role, and assign the role to all users that should have this right in a given context.</p>
+    <p>See <a href="advanced.htm#rights"><b>Advanced</b> -> <b>Roles and permissions</b></a> for more details</p>
+
+    <h2>Configuration</h2>
+    <p>After installing the plugin you can find the main configuration in <b>Site administration</b> -> <b>Courses</b> -> <b>Studyplans</b></p>
+    <p><img src="img/Siteconfig.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>The page <a href="configuration.htm"><b>Configuration</b></a> gives more details about the configuration options</p>
 
 </div>

doc/view-studyplan.htm

@@ -9,8 +9,107 @@
         <li class="nav-item"><a class="nav-link " href="configuration.htm">Configuration</a></li>
     </ul>
     <h2>Using the studyplan - for students</h2>
-    <p>If you followed the post-install instructions, then every student associated with a studyplan will have the link "</p>
+    <p>If you followed the post-install instructions, then every student associated with a studyplan will have the link <i>My studyplan</i>
+    in the top menu.</p>
+    <p><img src="img/Student-link-mystudyplan.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>Clicking on this link shows the student all studyplans they are enrolled in as tabs.</p>
+    <p><img src="img/Student-studyplan.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>Each course has it's current outcome displayed with an icon and a color. The arrows protruding from the courses also show the color of it's icon</p>
+    <table>
+        <tr>
+            <th>Meaning</th>
+            <th class="pr-3 pl-3">Icon</th>
+            <th>Color</th>
+            <th class="pl-3">Remarks</th>
+        </tr>
+        <tr>
+            <td>Completed (generic)</td>
+            <td class="text-center"><i title="Completed" style="float: none;" class="r-course-result fa fa-check-circle r-completion-complete"></i></td>
+            <td>Bootstrap color variable <i>--blue</i></td>
+            td class="pl-3">(Used only in the <i>Moodle course completion</i> studyplan aggregation methods)</td>
+        </tr>
+        <tr>
+            <td>Completed Passed</td>
+            <td class="text-center"><i title="Completed" style="float: none;" class="r-course-result fa fa-check-circle r-completion-completed"></i></td>
+            <td>Bootstrap color variable <i>--success</i></td>
+        </tr>        
+        <tr>
+            <td>Good</td>
+            <td class="text-center"><i title="Good" style="float: none;" class="r-course-result fa fa-check-circle r-completion-good"></i></td>
+            <td>Bootstrap color variable <i>--info</i></td>
+            <td class="pl-3">(Used only in the <i>Manual</i> studyplan aggregation methods)</td>
+        </tr>
+        <tr>
+            <td>Excellent</td>
+            <td class="text-center"><i title="Excellent" style="float: none;" class="r-course-result fa fa-check-circle r-completion-excellent"></i></td>
+            <td>Bootstrap color variable <i>--blue</i></td>
+            <td class="pl-3">(Used only in the <i>Manual</i> studyplan aggregation methods)</td>
+        </tr>
+        <tr>
+            <td>Progress/Not yet completed</td>
+            <td class="text-center"><i title="In progress" style="float: none;" class="r-course-result fa fa-exclamation-circle r-completion-progress"></i></td>
+            <td>Bootstrap color variable <i>--warning</i></td>
+        </tr>
+        <tr>
+            <td>Failed</td>
+            <td class="text-center"><i title="In progress" style="float: none;" class="r-course-result fa fa-times-circle r-completion-failed"></i></td>
+            <td>Bootstrap color variable <i>--danger</i></td>
+        </tr>        
+        <tr>
+            <td>Not started</td>
+            <td class="text-center"><i title="Not started" style="float: none;" class="r-course-result fa fa-circle-o r-completion-incomplete"></i></td>
+            <td>Bootstrap color variable <i>--gray</i></td>
+        </tr>      
+    </table>
+    <br>
+    <p> As you can see, the used colors depend on your theme. The configured colors for <i>success</i>, <i>warning</i>, <i>danger</i> and <i>info</i> are all
+        used. If you wish to further configure the colors, you can choose to redefine the other variables (e.g. <i>--blue</i> and <i>--gray</i>) your theme's
+        SCSS additions.
+    </p>
+    <p> By coloring the arrows in the color of the progress, both students and teachers can quickly see a student's progress in a course</p>
+    <p> Study plans that use the <i>Moodle course completion</i> aggregation method show a small circle that shows the progress percentage of all requirements, 
+        instead of an icon</p>
     
+    <h2>Course detail view</h2>
+    By clicking on a course, a student can view more details about this course.
+    <p>By clicking on the <b>course title</b>, or any of the <b>activities</b> the student is directly sent to the course or activity page, in a new tab.</p>
     
+    <h3>Moodle course completion view</h3>
+    <p><img src="img/Student-coursedetails-corecompletion.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>Per completion requirement, it is shown whether or not the student has <b>completed</b>, <b>passed</b> or <b>failed</b> the requirement.</p>
+    <p>The completion categories have a circle showing the progress in this category, while the status indicator to the top right shows the total status</p>
+    <p>Until the course end date has passed, the end status is marked as <b>progress</b> as long as one or more requirements are met or graded.
+       <i>After</i> the course end date has passed, ther course is indicated as <b>failed</b> if the completion requirements are not met</p>
+    <p> By clicking on the <a  class="s-required complete"><i class="fa fa-question-circle"></i></a> icon, the student can see the specific requirements for each
+        condition or activity.</p>
+    <p>If a teacher left feedback for an activity, the link <i>View feedback</i> is shownand shows the specific feedback upon clicking it.</p>
 
+    <h3>Manual view</h3>
+    <p><img src="img/Student-coursedetails-manual.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>Per selected activity, it is indicated if the student has completed this activity or not</p>
+    <p>Until the course end date has passed, the end status is marked as <b>progress</b> as long as one or more requirements are met or graded.
+        <i>After</i> the course end date has passed, ther course is indicated as <b>failed</b> if the completion requirements are not met 
+        <b>and the failed option is enabled</b> in the studplan configuration</b></p>
+    <p>If a teacher left feedback for an activity, the link <i>View feedback</i> is shownand shows the specific feedback upon clicking it.</p>
+    <p>(This is due to the specific grading requirements of the first school to request the study plan plugin)</p>
+
+    <h2>Sharing the study plan</h2>
+    <p>All students have the <a class="btn btn-primary" id="manage_invites"><i class="fa fa-share"></i> Share studyplan access</a> button</p>
+    <p>Using this button, the student can share access to their studyplan with anyone they choose. (Generally it is recommended that students share therein
+        study plan with their parents)
+    </p>
+    <p>The student first enters the <i>Invite management</i> page where they can add, remove, edit or re-send invitations</p>
+    <p><img src="img/Share-studyplan-manage.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>By clicking the <i class="fa fa-eye text-primary"></i> icon, the student can verify how their invitees see the studyplan</p>
+    <p>the other icons are respecively 
+        <i class="fa fa-envelope text-primary">re-send mail</i>, 
+        <i class="fa fa-pencil text-primary">edit</i> and 
+        <i class="fa fa-trash text-primary">delete</i></p>
+
+    <p>When starting a new invite, the student is asked to provide the <i>name</i> and <i>email</i> of the person to send the invitation to</p>
+    <p><img src="img/Share-studyplan-add.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>After completing the invitation, the system sends an email to the invitee with a unique link specific to the invitee. By clicking the link,
+        the invitee can see the student's study plan, grades and provided feedback.
+    </p>
+    <p>Upon deleting the invitation, the unique link is immediately deactivated and all access the invitee had to view the student's studyplan is revoked.</p>
 </div>