Documentation

doc.php

@@ -0,0 +1,33 @@
+<?php
+require_once("../../config.php");
+
+require_once($CFG->libdir.'/weblib.php');
+
+$systemcontext = context_system::instance();
+
+$PAGE->set_url("/local/treestudyplan/doc.php",array());
+$PAGE->set_pagelayout('base');
+$PAGE->set_context($systemcontext);
+require_login();
+
+$pi = $_SERVER['PATH_INFO'];
+$file = $CFG->dirroot."/local/treestudyplan/doc".$pi;
+
+// Fallback to index
+if(!file_exists($file)){
+	$file = $CFG->dirroot."/local/treestudyplan/doc/index.htm";
+}
+
+$mime = mime_content_type($file);
+$text_types = ["text/html","text/plain"];
+
+if( in_array($mime,$text_types))
+{
+	print $OUTPUT->header();
+	print file_get_contents($file);
+	print $OUTPUT->footer();
+}
+else {
+	header("Content-type: {$mime}");
+	print file_get_contents($file);
+}

doc/index.htm

@@ -0,0 +1,142 @@
+<div>
+    <h1> Studyplan user manual</h1>
+    <ul class="">
+        <li><a href="#about">About studyplan</a></li>
+        <li><a href="#postinstall">Post installation config</a></li>
+        <li><a href="#setup">Configuration</a></li>
+        <li><a href="#createstudyplan">Creating a study plan></a></li>
+    </ul>
+    <a id="#about"><h2>About studyplan</h2></a>
+    <p>The studyplan plugin extends Moodle with the ability to show students and teachers an overview of their curriculum and results therein</p>
+    <p>By showing students an easy to read graphical overview of their progress over multiple courses, students are more in control of their own
+    learning process than by just listing results alone</p>
+
+    <a id="#postinstall"><h2>Configuration post install</h2></a>
+    <p>The studyplan plugin will automatically add links to the flat navigation bat used in Moodle 3.11 and below<p>
+    <p>However, Moodle 4.0-4.2 use a new "primary navigation" bar, and does not yet support customizing the primary navigation bar (it is a planned feature though)</p>
+        
+    <p><strong>Use the following workaround:</strong></p>
+    <p>You can add custom primary menu items in <b>Site administration</b> -> <b>Appearance</b>-> <b>Theme settings</b>
+        That page contains an item called Custom menu items". Add the following into that area to custimize it
+    </p>
+    <p><pre >
+Mijn studieplan|/local/treestudyplan/myreport.php||nl
+Studieplannen|/local/treestudyplan/view-plan.php||nl
+Studieplannen beheren|/local/treestudyplan/edit-plan.php||nl
+My study plan|/local/treestudyplan/myreport.php||en
+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>
+    After installing the plugin you can find the main configuration in <b>Site administration</b> -> <b>Courses</b> -> <b>Studyplans</b>
+    <br>
+    <img src="img/Siteconfig.png" class="border border-primary rounded-lg ml-3">
+    <a id="createstudyplan"><h2>Creating a study plan</h2></a>
+    <p>To create a studyplan, go to <b>Site administration</b> -> <b>Courses</b> -> <b>Studyplans</b> -> <b>Manage Studyplans</b></p>
+    <p>You will now see a screen like the following</p>
+    <p><img src="img/Createstudyplan.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>If you do not yet have an exported studyplan to import, pick <b>Add study plan</b> to create a new study plan</p>
+    <p>You are now asked to provide details for this new studyplan</p>
+    <p><img src="img/Newstudyplanscreen.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>The screen allows you to specify the <b>full name</b>, <b>code</b> or short name and <b>description</b> for this specific plan</p>
+    <p>You can also choose the category <b>context</b> in which to place this study plan. This is useful to manage access rights in a large moodle installation</p>
+    <p>The next options give more information about the timing of the plan. The <b>number of slots</b> to place courses in the plan can be specified. 
+        This is usually used to show the different periods in the academic year. You can expect this to become more explicit in upcoming versions of the plugin.
+        The <b>start date</b> and <b>end date</b> of the plan help to show students and teachers which plans are current, and which were finished in the past. 
+        They will default to start on august 1 of this year and continue until august 1 of next year, since that matches most academic years.</p>
+    <p>Finally we have the <b>aggregation style</b>, which is ised to determine how the courses show grades. There are a number of options available:</p>
+    <ul>
+        <li><b>Moodle course completion</b> <i>This is the recommended method to use.</i> All the conditions selected in the moodle course completion will be shown in the progress list.</li>
+        <li><b>Manual: Completed + required goals</b>Manually select a number of gradable activities from the course, which will be used to determine grade. Extra options for this method</li>
+        <li><b>Manual: Progress/Completed/Excellent classic</b> <i>Deprecated! Do not use!</i> This is an old and convoluted method that is only in here for compatibility reasons</li>
+    </ul>
+    <h3>Details for Manual: Completed + required goals</h3>
+    <p>
+        With this aggregation method you manually select which grade items are used in the progress report. The design intent is to prepare a number of gradable items,
+        and describe the learning objectives for each course and use these to indicate completion. While any grade will be properly shown, it makes most sense to use a scale which indicates
+        if the student has either met the objective or not. The teacher or studyplan editor can also mark certain gradables/objectives as required or compulsory. 
+    </p>
+    <p>The final outcome for the courses will then be determined based on the percentage of met objectives, provided that all required/compulsory objectives are met</p>
+    <p><img src="img/Newstudyplanscreen.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>The added options allow you to set the <b>threshold</b> percentage of completed objectives in each course to determine the outcome as <i>excellent</i>, <i>good</i>
+        or <i>completed</i>. If an objective is not met it will be marked as either "progress" (meaning that the student's work needs to be improved) or 
+        "incomplete" (meaning that the student has not started working on this goal yet) </p>
+    <p>When <i>failed</i> results are enabled, any "progress" will be marked as "failed" when the course end date has passed</p>
+    <p>Finally, you can opt to have an object ive </p>
+    <a id="studylines"><h2>Setting up studylines</h2></a>
+    <p>Before you can add courses to the studyplan, you have to define <i>study lines</i>. You use them to group together courses in logical categories. 
+        Most likely these are categories or themes within your curriculum.</p>
+    <p>For performance reasons, study lines can only be edited when in <i>study line edit mode</i>. The courses and flow between them will be hidden,
+        so the lines can be reshuffled and edited. You can toggle studyline edit mode with the toggle switch <i>edit stydy lines</i></p>
+    <p><img src="img/AddStudylines-overview.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>Using the <b>Add study line</b> link, you can add a new studyline. You will then get a new window where you can enter details and select a handle color for this line</p>
+    <p><img src="img/AddStudyline-modal.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>Here you can enter a <b>full name</b> for the study line that will be shown when you hover over the name, and a <b>code</b> that is a short name which will be shown
+    in front of the study line. Often this can be a short code. The <b>color</b> you pick will be shown in a little tab in front of the study line.</p>
+    <p>You can <i>drag</i> study lines to re-order them after you place them using the <i class="fa fa-arrows"></i> crosshair arrows</p>
+    <p>Using the <i class="fa fa-pencil"></i> and <i class="fa fa-trash"></i> symbols you can edit and delete the studyline (only empty studylines can be deleted)</p>
+    <p><img src="img/Studylines-view.png" class="border border-primary rounded-lg ml-3"></p>
+    <div class="generalbox alert alert-info"><b>TIP:</b><br>
+    If you have many studyplans using the same study line make-up you can export the first studyplan after you set up the study lines, and then import it on the next 
+    study plans.<br>(Use <b>Advanced</b> -> <b>Backup studyplan</b> to find the <i>backup</i> and <i>restore</i> features)</div>
+    
+    <a id="studycourses"><h2>Adding courses</h2></a>
+    <p>To add courses, you need to exit <i>study line edit mode</i> and open the toolbox using the <button class="btn btn-primary">Open toolbox</button> button. 
+        The toolbox will now open on the right of the screen. (Using the toggle button on top, you can also switch it to the left of the screen if needed)</p>
+    <p><img src="img/Toolbox-Courses.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>The toolbox shows you all the categories you have access to and the courses in them. Simply drag the course you want to include from the toolbox and 
+        drop it in one of the slots in the studyplan that now appear.</p>
+    <p><img src="img/Toolbox-dragcourse.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>To re-arrange the courses in the study plan, simply drag and drop them from the places they are now in.</p>
+    <p><img src="img/Studyitem-dragdelete.png" class="border border-primary rounded-lg ml-3"></p>
+    <p>To remove a course from the study plan, simply drag it to the red garbage bin that appears on dragging</p>
+    <a id="studycourses"><h2>Configuring courses</h2></a>
+    <p>Once a course is added to the studyplan, an icon shows if it needs to be configured (<i class='fa fa-exclamation-circle text-warning'></i>) or 
+        is already configured (<i class='fa fa-check text-success'></i>).</p>
+    <p>By clicking on the course title (it's shortname, or a configured custom field), you can view the details, and configure it where applicable.
+        The configuration is dependent on the aggregation method for the study plan:</p>
+    <h3>Moodle course completion</h3>
+    <p>When using moodle course completion as a base, all configuration is done in the <i>course's completion settings</i>. 
+        The course details show a <i class='fa fa-gear primary'></i> gear icon in the title, which takes you directly to the course completion configuration.
+        Once it is configured, the course details will show you exactly how the course completion is configured</p>
+    <p><img src="img/Course-config-corecompletion.png" class="border border-primary rounded-lg ml-3"></p>
+
+    <h3>Manual: Completed + required goals</h3>
+    <p> In this mode, the course details show you all the gradable activities in the course. You need to select which of them will be used to determine progress
+        and will be shown to the students and teachers in the studyplan view. You can also mark gradables ad <i>required</i>. Gradable activities marked as 
+        such will all need to be completed for the course to be marked as completed, regardless of the minimum percentage configured</p>
+    <p><img src="img/Course-config-bistate.png" class="border border-primary rounded-lg ml-3"></p>
+
+    <a id="studybadges"><h2>Adding badges</h2></a>
+    <p>The toolbox also shows you the site-wide badges that are available for students. These can be dragged into the slots around and between the courses.</p>
+    <p>When you click on the <i class="fa fa-gear"></i> icon in the badge it shows you additional information about the badge</p>
+    <p><img src="img/Toolbox-badges.png" class="border border-primary rounded-lg ml-3"></p>
+    <a id="flow"><h2>Drawing the flow</h2></a>
+    <p>You can draw arrows between the courses and add flow indicators to show students how different courses are related in the studyplan</p>
+    <h3>Drawing arrows</h3>
+    <p> </p>
+    <h3>Removing arrows</h3>
+    <p> </p>
+    <h3>Adding flow indicators</hr>
+    <p><img src="img/Toolbox-flow.png" class="border border-primary rounded-lg ml-3"></p>
+    <p> You can add the following flow indicators:</p>
+        <ul>
+            <li><b>Junction</b> Used to combine the results of multiple arrows. The color and resulting arrow will be based on the combination of the incoming arrows</li>
+            <li><b>Finish</b> Used to indicate the end of a study line. It's color is based on the combination of the incoming arrows, just like the junction </li>
+            <li><b>Start/continue</b> These indicators are always green and can be used to indicate the start of a series of courses</li>
+        </ul>
+    <p> By clicking on the <i class="fa fa-gear"></i> icon in the junction and finish indicators, you can select how the incoming arrows will be combined. 
+        The indicated numer of arrows need to be completed in order to show the indicator as completed</p>
+    <ul>
+        <li><b>All entries</b></li>
+        <li><b>2/3 of entries</b></li>
+        <li><b>Half of entries</b></li>
+        <li><b>All entries</b></li>
+    </ul>
+    <div class="generalbox alert alert-info"><b>Note:</b><br>
+        Using the <i>Manual</i> aggregation method, these conditions are also used to determine whether a junction or finish will be shown as <i>good</i> or <i>excellent</i>
+        In those cases, at least the specified number of arrows need to be  <i>good</i> or <i>excellent</i> in order to color the indicator as such.</div>
+        
+
+</div>

lang/en/local_treestudyplan.php

@@ -80,6 +80,7 @@ $string['studyplan_remove'] = 'Remove study plan';
 $string['studyplan_confirm_remove'] = 'Are you sure you want to remove studyplan {$a}?';
 $string['studyplan_name'] = 'Full name';
 $string['studyplan_name_ph'] = '';
+$string['studyplan_context'] = 'Context';
 $string['studyplan_shortname'] = 'Code';
 $string['studyplan_shortname_ph'] = '';
 $string['studyplan_description'] = 'Description';

lang/nl/local_treestudyplan.php

@@ -82,6 +82,7 @@ $string['studyplan_remove'] = 'Studieplan verwijderen';
 $string['studyplan_confirm_remove'] = 'Weet je zeker dat je studieplan {$a} wilt verwijderen?';
 $string['studyplan_name'] = 'Naam';
 $string['studyplan_name_ph'] = '';
+$string['studyplan_context'] = 'Context';
 $string['studyplan_shortname'] = 'Code';
 $string['studyplan_shortname_ph'] = '';
 $string['studyplan_description'] = 'Beschrijving';