MoodleDocs - User contributions [en]

Development talk:Backup 2.0 - Converters review 2011-04

2011-04-28T19:53:16Z

Bushido: /* Feedback from Mark regarding review */

Please, for discussing any of the points in the page, do it in the corresponding MDL-xxx issue in the Tracker. TIA! --[[User:Eloy Lafuente (stronk7)|Eloy Lafuente (stronk7)]] 22:45, 26 April 2011 (WST)

=== Ongoing discussion Eloy & Mark (20110428) ===

Three (3) targets are planned, no action on next target will be performed before completing the previous one:

* The "basic" (1st): Be able to restore everything but user-related information.
* The "desirable" (2nd): Be able to restore activity user-related information.
* The "complete" (3rd): Rest of information.

----

From the review, points 01-19 must be analyzed, discussed and implemented, specially the ones detected as blockers for the consecution of the targets above. The ones not being considered blockers can be left for later, once the "basic" (1st) target has been fulfilled. The review page will show which ones are considered blockers and where (MDL-xxxx) their implementation is going to happen.

----

Immediate plan, something like:
* you take a look to those points and add any objection / comment / missing point in the last section of the page.
* I also take a look to the thing and start implementing some stuff, like the start/end dispatchers and some tests to have them under control.
* Next day, availability of parties determined, we share thoughts.
* Next-next day, we start "doing" things :-)

=== Feedback from Mark regarding review ===

==== Related to integration with restore_controller & general behavior ====

* R0401: I see what you are trying to get at here, but seems like over architecting IMO. For example, you have something that goes from FOO > BAR > MOODLE2 (CONVERTPATH1) and then you have something that goes to FOO > MOODLE2 (CONVERTPATH2) both installed, then your proposal would be necessary. Though, why would you have both installed? CONVERTPATH2 would replace CONVERTPATH1 making CONVERTPATH1 obsolete and never used anyways. Anyways, I'd say let's hold this off as a fun project after everything else is done.
* R0402: I don't see much of an advantage here as by moving to static you then loose access to all of your instance variables and methods. Cost of creating a new instance shouldn't be that terrible. If this is required, fine, let's do it.
** As for checking the environment, I think that can be done in can_convert right? Part of figuring out if it can handle the conversion.
* R0403-5: These are fine. We should probably make our own converter_exceptions, what do you think?

==== Related to the converters/moodle1 infrastructure ====

* R0408: There is execute_after_convert but really, that's called after the XML has been processed. Execution flow is kind of weird due to the processor. We could add another stage of processing, though I do think execution flow will greatly improve once start/end callbacks are being used.
* R0410: I'm not sure what this is.
* Rest are fine.

==== Related to coding in general ====

* Sounds fine.

Development talk:Backup 2.0 - Converters review 2011-04

2011-04-28T19:19:48Z

Bushido:

Course formats

2011-04-26T17:06:52Z

Bushido: /* Page format */

A course format refers to the layout of a course. They can be changed by the course [[Course administration block]] under [[Course settings|settings]].

==Standard course formats==

===Weekly format===
[[Image:Course top weekly mu1.jpg|thumb|Weekly format example]] The course is organized week by week, with a clear start date and a finish date. Moodle will create a section for each week of your course. You can add content, forums, quizzes, and so on in the section for each week.

:''TIP:'' If you want all your students to work on the same materials at the same time, this would be a good format to choose.

:''NOTE:'' Make sure your course start date is correct. If it is not your weeks will have the wrong date on it. This is especially important if you are restoring a course to use with a new section of students.

===Topics format===
The course is organised into topic sections. Each topic section consists of activities.

TIP: This is great to use if your course is objective based and each objective may take different amounts of time to complete. An example of this would be scaffolding where the students are building upon the knowledge from earlier topics.

===Social format===
[[Image:Course top social mu1.jpg|thumb|Social format example]] This format is oriented around one main [[Forum module|forum]], the social forum, which appears listed on the main page. It is useful for situations that are more free form. They may not even be courses. The [http://moodle.org/course/view.php?id=55 Moodle Lounge] is an example of a social format course.

The social forum can be edited by clicking the 'Update this forum' button on the social forum page. The forum introduction is displayed at the top of the course page (in Moodle 1.9.5 onwards).

===LAMS course format===
[[LAMS|The Learning Activity Management System]] is an open source LMS which allows teachers to use a flash based authoring environment for developing learning sequences. LAMS has been integrated with Moodle to allow teachers to develop LAMS activities within a Moodle course. This course format makes LAMS central to the course, only displaying the LAMS interface.

:''TIP:'' If you are interested in using LAMS, check with your system administrator to see if they have installed and configured LAMS. Very few institutions use LAMS as it duplicates much of the Moodle functionality.

===SCORM format===
The [[SCORM/AICC module|Sharable Content Reference Model]] (SCORM) is a content packaging standard. SCORM packages are self-contained bundles of content and JavaScript activities, which can send data to Moodle about the students score and current location. Moodle can use SCORM packages as a content type (see [[SCORM/AICC module]]), or as a course format.

:''TIP:'' If you have a large SCORM object you want to use as an entire course, then you can select this course format and students will only be able to interact with the SCORM object, not the rest of the Moodle tools.

===Weekly format, CSS/no tables===
The CSS / No Tables variant of the Weekly format displays the Weekly course format without using tables for layout. This improves the accessibility of the format, but older browsers have trouble displaying it correctly. This format is available in Moodle 1.6 onwards.

==Contributed course formats==

===Page format===
Also known as Flexpage, this format is very similar to the Book resource format in a Moodle course. It consists of a theme, course format, and menu module which enables blocks and modules to be intermixed on a 3 column layout, provide tab based navigation through course content, inline display of resources and forums, etc. For more information on Flexpage, please visit [http://development.moodlerooms.com/course/view.php?id=34 this site] (You can self-register for this Moodle course.) This feature was developed by a Moodle partner [http://www.moodlerooms.com Moodlerooms, Inc.]

===Collapsed Topics and Weeks formats===

Collapsed Topics and its sister format, Collapsed Weeks are formats that are essentially the same as the standard Topic ([[Course_sections#Topics_format]]) and Weekly ([[Course_sections#Weekly_format]]) formats but with a 'toggle' for each section except '0'. The toggles' purpose is to reduce the amount of initial information presented to the user thus reducing the 'scroll of death' that can plague courses with a lot of content. The 'state' of the toggles is remembered on a per course per user basis. Collapsed Weeks automatically opens the current week. There are versions available for Moodle 1.8, 1.9 and 2.0. For more information, please visit [[Collapsed_Topics_course_format]] and [[Collapsed_Weeks_course_format]].

===Other contributed course formats===

Other contributed course formats include [[Project Course Format]], [[Weekly Tabs]], Monthly Format (for Moodle 1.9), [[Development:Timeline course format|Timeline course format]] and the [[Shared activities course format]].

An administrator wishing to remove installed formats may do so by removing the format plugin from the installation. That is: remove the directory containing the format for the ''moodle/course/format'' directory. You probably should not remove any of the default course formats, or formats that are in use on the site.

==See also==

*[[Course settings]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=47 Course formats forum]
*[http://www.moodleman.net/archives/47 Getting the most out of course design] blog post describing various contributed course formats

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=116428 Social format: where to put an introduction]
*[http://moodle.org/mod/forum/discuss.php?d=136453 RSS Feed for forum in a Social Format course]

[[Category:Course format]]

[[fr:Formats de cours]]

[[es:FormatoCurso]]

Development:Auth External Database Release Notes

2009-02-04T23:50:04Z

Bushido: New page: * Added more data mappings: ** maildigest ** autosubscribe ** trackforums ** password * Implemented the cron method. * Added unlimited execution time for auth/db/auth_db_sync_users.php * N...

* Added more data mappings:
** maildigest
** autosubscribe
** trackforums
** password
* Implemented the cron method.
* Added unlimited execution time for auth/db/auth_db_sync_users.php
* New settings when Password format is set to internal:
** Create Unique Password: If the password type is set to internal then this setting determines if a unique password is created and emailed to the user's email address in the external datbase.
** Only Change this Password: Adding a value to this field causes moodle to only create a password for those users that have their password set to the value. For example changeme will cause all users with the password changeme to have a unique password created and emailed to them. Leave this blank if you want to change all users password when their acocunt is first created.
** Force Password Change: If the password type is set to internal then this setting determines if the user is forced to change their password on their first login
* Performance improvements:
** With original code, attempted to create 100,000 users and execution was terminated after waiting for a long time (hour or more).
** With the new code, created 20,000 users in 36 seconds and 100,000 users in 188 seconds.

Development:New lesson navigation

2009-01-21T18:55:50Z

Bushido: Adding note about replacing branch tables with check points

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
**If student received 100% of the possible points on the last question, go to ''this'' page. If 99% to 60%, go to ''this'' page. If less than 60%, go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).
*Visible Check Point: the user is presented with text and buttons with labels. The buttons are navigational choices for the user. This is the same fundamental functionality found in current lesson [[Branch_Table|Branch Tables]].

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced with Check Points. (Branch tables could be replaced, see above section Possible uses: Visible Check Points [[User:Mark Nielsen|Mark Nielsen]] 12:55, 21 January 2009 (CST))

===Advantages===

*'''Primary:''' this would make the transition to the question type class more natural. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.
*Lesson question will strictly be used for grading, no customized jumps depending upon a specific answer.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

==See also==
*[[Development:Lesson Specification]]
*[[Development:Adding blocks to lesson]]
*[[Development:Adding question types to lesson]]

[[Category:Developer|New lesson navigation]]
[[Category:Lesson]]

Development:New lesson navigation

2009-01-21T18:53:58Z

Bushido: Added new possible use: visible check point

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
**If student received 100% of the possible points on the last question, go to ''this'' page. If 99% to 60%, go to ''this'' page. If less than 60%, go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).
*Visible Check Point: the user is presented with text and buttons with labels. The buttons are navigational choices for the user. This is the same fundamental functionality found in current lesson [[Branch_Table|Branch Tables]].

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced with Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class more natural. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.
*Lesson question will strictly be used for grading, no customized jumps depending upon a specific answer.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

==See also==
*[[Development:Lesson Specification]]
*[[Development:Adding blocks to lesson]]
*[[Development:Adding question types to lesson]]

[[Category:Developer|New lesson navigation]]
[[Category:Lesson]]

Development:Adding question types to lesson

2009-01-21T18:46:57Z

Bushido: Added a new comment: Branch tables == visible check points

{{Moodle 2.0}}
Please note that this page deals with a future version of [[Roadmap#Version_2.0|Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson module]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*(Primary) Increase the usability of the lesson module by making it easier for lesson authors to construct lessons.
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
**Will this include the shuffle answer option for each question, or will/can this be a Lesson setting?--[[User:chris collman|chris collman]] 08:37, 10 December 2007 (CST)
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

:Not tracking individual student answers in a lesson would clearly separate Lesson from Quiz. I like it. I believe once we have at least some sort of course dependency in Moodle 2, this will take a great deal of pressure off of Lesson. The course dependency setting for any activity should at least have greater, less than choices from say a score or one or more activities/resources. (this seems similar to the State Checker idea). It would be nice if it had limited nested if/then statements to allow a ranges of dependency to be really adaptive. This will allow the teacher to break up big lessons into smaller ones and put a real quiz/test between them. So when the student gets a 100% on a following quiz, they go to Lesson 10, but the student who scores less than 50% goes back to the Lesson or to a special lesson before they will see Lesson 10. Under these conditions, we can confidently get rid of a history of answered questions in Lesson, and leave that function to Quiz. --[[User:chris collman|chris collman]] 10:06, 8 November 2008 (CST)

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).
*migrate lesson navigation.

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

''<comment>''

I think you can use this without invasions. The questions contain feedback (which is a rought equivalent of outcome), and the answers with equivalent feedbacks are very likely to give equivalent jumps (if they still not, user can easily rewrite it using different words or just add some spaces or punctuation). You may not invade in the question types, but use feedback they return instead. You can use a table (apart from question editing interface) that allows author to specify jumps for feedbacks (or place jump right in feedback in some sort of you own tag - but it'll restricts using one question on several pages or lessons with different jumps). This solution is quite easy to implement, probably an easier way than anyone mentioned there.

You can get problem with some question types using this, but they are easily solved:
* essay - you probably will want to suppress using of manual graded question types in lessons anyway;
*multichoice in several choices mode - you can use correct/partial/incorrect feedbacks;
*match - it lacks feedbacks now, but probably it must have just correct/partial/incorrect as multichoice question, they are needed in it anyway, not only for the lessons.

You may want to use feedback text only as values to communicate with user thought, replacing it in database by subquestion id or code for correct, partial or incorrect values. This allows you to avoid problems with editing feedbacks for existing questions.

''</comment>'' --[[User:Oleg Sychev|Oleg Sychev]] 08:52, 13 November 2008 (CST)

====A new path====

''by [[User:Mark Nielsen|Mark Nielsen]] 13:43, 13 November 2006 (CST)''

After a nice discussion with [http://moodle.org/user/view.php?id=3432&course=5 Michael Penney], a new solution to this problem arose. Instead of working with the current method of each question having a set of defined jumps, instead introduce a new feature called ''state checker'' (the name at the moment, could change later). These ''state checkers'' could be inserted throughout the lesson and are used to determine the navigation. These ''state checkers'' could be set to say, ''if student has more than 70% correct then send the student to location X, otherwise send student to location Y.'' Alternatively, the ''state checker'' could be set to say ''if last question was correct, go to X otherwise go to Y''. These examples are binary, but the ''state checker'', when fully implemented, should allow several more options and more granular control.

'''Pros for this implementation:'''
*No major changes are required to the question bank code.
*Since the navigational control logic is separate from the question logic, one cannot accidentally modify or break a lesson's navigation by editing a question.
*Lesson navigation can be controlled via one screen and '''is independent of questions'''.
*More possibilities for lesson navigation control.
*Could reduce the complexity of the multi-stage UI that the other solutions require.
'''Cons:'''
*Migration of old navigation structure could prove to be complicated depending on how the ''state checker'' would be developed (NOTE: this is already a problem. See next section ''Migration of jumps'').

''<comment>''

:If State Checkers are used, then there should be an overall default for how one navigates from one page/question to the next. EG: Correct answer goes to next page in the logical order, Wrong answer goes to same page. Then one adds State Checkers to change the default navigation of the lesson. There should be several configurable default navigations to choose from in the lesson settings.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 16:17, 24 March 2007 (CDT)

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson module#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Comments on questions and jumps===
I think the adaptive jumps of Lesson are a key feature. If I read the above correctly, I don't like limiting this to either a correct answer jump or a wrong answer jump. I do like the concept of a jump form. --[[User:chris collman|chris collman]] 09:49, 8 November 2008 (CST)

This also begs the special navigation features used in clusters and 'branches" with end of Branch which Mark has addressed with [[Development:New_lesson_navigation#Check_Points|Check Points]] which I assume are different that State Checkers.I know nothing about elegance, and that is why I like to write about what developers have created :)--[[User:chris collman|chris collman]] 09:49, 8 November 2008 (CST)

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson module#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.
:Branch tables are grade neutral. That means neither 0% nor 100% credit for any answers or else it will count towards the grade/score. I do not have a issue with a descriptive page, except I would call it a "Choice page" and make it essentially a grade neutral multiple choice question. This would also allow graphics next to a choice, something not possible with a Branch Table.--[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)

:Branch tables, offer the student choices and description question types do not offer any choices. This is a big difference. Perhaps a description question needs the ever present "continue" choice when it will be imported into Lesson from Question Bank.--[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)

:This could also make importing OOwriter and OOimpress pages easier into Lesson. I am still hopeful that something like the GIFT format will allow pages to be imported and exported from Lesson. With the State checker and [[Development:New_lesson_navigation#Check_Points|Check Points]] kind of concepts, this would make that task easier. Perhaps come up with some standard code to attach a state checker to the page? --[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)

:Wanted to jot down a random though, a branch table could perhaps just be a visible Check Point with buttons to allow the user to choose where to go next. More I think about this, the better it gets, code wise and lesson editing wise. [[User:Mark Nielsen|Mark Nielsen]] 12:46, 21 January 2009 (CST)

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

:See discussion about making branch pages more like description questions in Quiz. Or converting Branch tables to a grade neutral format similar to a multiple choice question, where there are no buttons but graphics are allowed.

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson module|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.
*[[Development:New lesson navigation]]
*[[Development:Lesson Specification]]
*[[Development:Adding blocks to lesson]]

[[Category:Moodle 2.0]]
[[Category:Developer|Adding question types to lesson]]
[[Category:Lesson]]

Development:Adding question types to lesson

2009-01-21T18:40:05Z

Bushido: Added new pro: separation of logic to prevent accidently breaking lesson navigation

{{Moodle 2.0}}
Please note that this page deals with a future version of [[Roadmap#Version_2.0|Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson module]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*(Primary) Increase the usability of the lesson module by making it easier for lesson authors to construct lessons.
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
**Will this include the shuffle answer option for each question, or will/can this be a Lesson setting?--[[User:chris collman|chris collman]] 08:37, 10 December 2007 (CST)
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

:Not tracking individual student answers in a lesson would clearly separate Lesson from Quiz. I like it. I believe once we have at least some sort of course dependency in Moodle 2, this will take a great deal of pressure off of Lesson. The course dependency setting for any activity should at least have greater, less than choices from say a score or one or more activities/resources. (this seems similar to the State Checker idea). It would be nice if it had limited nested if/then statements to allow a ranges of dependency to be really adaptive. This will allow the teacher to break up big lessons into smaller ones and put a real quiz/test between them. So when the student gets a 100% on a following quiz, they go to Lesson 10, but the student who scores less than 50% goes back to the Lesson or to a special lesson before they will see Lesson 10. Under these conditions, we can confidently get rid of a history of answered questions in Lesson, and leave that function to Quiz. --[[User:chris collman|chris collman]] 10:06, 8 November 2008 (CST)

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).
*migrate lesson navigation.

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

''<comment>''

I think you can use this without invasions. The questions contain feedback (which is a rought equivalent of outcome), and the answers with equivalent feedbacks are very likely to give equivalent jumps (if they still not, user can easily rewrite it using different words or just add some spaces or punctuation). You may not invade in the question types, but use feedback they return instead. You can use a table (apart from question editing interface) that allows author to specify jumps for feedbacks (or place jump right in feedback in some sort of you own tag - but it'll restricts using one question on several pages or lessons with different jumps). This solution is quite easy to implement, probably an easier way than anyone mentioned there.

You can get problem with some question types using this, but they are easily solved:
* essay - you probably will want to suppress using of manual graded question types in lessons anyway;
*multichoice in several choices mode - you can use correct/partial/incorrect feedbacks;
*match - it lacks feedbacks now, but probably it must have just correct/partial/incorrect as multichoice question, they are needed in it anyway, not only for the lessons.

You may want to use feedback text only as values to communicate with user thought, replacing it in database by subquestion id or code for correct, partial or incorrect values. This allows you to avoid problems with editing feedbacks for existing questions.

''</comment>'' --[[User:Oleg Sychev|Oleg Sychev]] 08:52, 13 November 2008 (CST)

====A new path====

''by [[User:Mark Nielsen|Mark Nielsen]] 13:43, 13 November 2006 (CST)''

After a nice discussion with [http://moodle.org/user/view.php?id=3432&course=5 Michael Penney], a new solution to this problem arose. Instead of working with the current method of each question having a set of defined jumps, instead introduce a new feature called ''state checker'' (the name at the moment, could change later). These ''state checkers'' could be inserted throughout the lesson and are used to determine the navigation. These ''state checkers'' could be set to say, ''if student has more than 70% correct then send the student to location X, otherwise send student to location Y.'' Alternatively, the ''state checker'' could be set to say ''if last question was correct, go to X otherwise go to Y''. These examples are binary, but the ''state checker'', when fully implemented, should allow several more options and more granular control.

'''Pros for this implementation:'''
*No major changes are required to the question bank code.
*Since the navigational control logic is separate from the question logic, one cannot accidentally modify or break a lesson's navigation by editing a question.
*Lesson navigation can be controlled via one screen and '''is independent of questions'''.
*More possibilities for lesson navigation control.
*Could reduce the complexity of the multi-stage UI that the other solutions require.
'''Cons:'''
*Migration of old navigation structure could prove to be complicated depending on how the ''state checker'' would be developed (NOTE: this is already a problem. See next section ''Migration of jumps'').

''<comment>''

:If State Checkers are used, then there should be an overall default for how one navigates from one page/question to the next. EG: Correct answer goes to next page in the logical order, Wrong answer goes to same page. Then one adds State Checkers to change the default navigation of the lesson. There should be several configurable default navigations to choose from in the lesson settings.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 16:17, 24 March 2007 (CDT)

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson module#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Comments on questions and jumps===
I think the adaptive jumps of Lesson are a key feature. If I read the above correctly, I don't like limiting this to either a correct answer jump or a wrong answer jump. I do like the concept of a jump form. --[[User:chris collman|chris collman]] 09:49, 8 November 2008 (CST)

This also begs the special navigation features used in clusters and 'branches" with end of Branch which Mark has addressed with [[Development:New_lesson_navigation#Check_Points|Check Points]] which I assume are different that State Checkers.I know nothing about elegance, and that is why I like to write about what developers have created :)--[[User:chris collman|chris collman]] 09:49, 8 November 2008 (CST)

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson module#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.
:Branch tables are grade neutral. That means neither 0% nor 100% credit for any answers or else it will count towards the grade/score. I do not have a issue with a descriptive page, except I would call it a "Choice page" and make it essentially a grade neutral multiple choice question. This would also allow graphics next to a choice, something not possible with a Branch Table.--[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)
:Branch tables, offer the student choices and description question types do not offer any choices. This is a big difference. Perhaps a description question needs the ever present "continue" choice when it will be imported into Lesson from Question Bank.--[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)
:This could also make importing OOwriter and OOimpress pages easier into Lesson. I am still hopeful that something like the GIFT format will allow pages to be imported and exported from Lesson. With the State checker and [[Development:New_lesson_navigation#Check_Points|Check Points]] kind of concepts, this would make that task easier. Perhaps come up with some standard code to attach a state checker to the page? --[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

:See discussion about making branch pages more like description questions in Quiz. Or converting Branch tables to a grade neutral format similar to a multiple choice question, where there are no buttons but graphics are allowed.

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson module|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.
*[[Development:New lesson navigation]]
*[[Development:Lesson Specification]]
*[[Development:Adding blocks to lesson]]

[[Category:Moodle 2.0]]
[[Category:Developer|Adding question types to lesson]]
[[Category:Lesson]]

Development:Adding question types to lesson

2009-01-21T17:39:29Z

Bushido: Added usability goal

{{Moodle 2.0}}
Please note that this page deals with a future version of [[Roadmap#Version_2.0|Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson module]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*(Primary) Increase the usability of the lesson module by making it easier for lesson authors to construct lessons.
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
**Will this include the shuffle answer option for each question, or will/can this be a Lesson setting?--[[User:chris collman|chris collman]] 08:37, 10 December 2007 (CST)
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

:Not tracking individual student answers in a lesson would clearly separate Lesson from Quiz. I like it. I believe once we have at least some sort of course dependency in Moodle 2, this will take a great deal of pressure off of Lesson. The course dependency setting for any activity should at least have greater, less than choices from say a score or one or more activities/resources. (this seems similar to the State Checker idea). It would be nice if it had limited nested if/then statements to allow a ranges of dependency to be really adaptive. This will allow the teacher to break up big lessons into smaller ones and put a real quiz/test between them. So when the student gets a 100% on a following quiz, they go to Lesson 10, but the student who scores less than 50% goes back to the Lesson or to a special lesson before they will see Lesson 10. Under these conditions, we can confidently get rid of a history of answered questions in Lesson, and leave that function to Quiz. --[[User:chris collman|chris collman]] 10:06, 8 November 2008 (CST)

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).
*migrate lesson navigation.

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

''<comment>''

I think you can use this without invasions. The questions contain feedback (which is a rought equivalent of outcome), and the answers with equivalent feedbacks are very likely to give equivalent jumps (if they still not, user can easily rewrite it using different words or just add some spaces or punctuation). You may not invade in the question types, but use feedback they return instead. You can use a table (apart from question editing interface) that allows author to specify jumps for feedbacks (or place jump right in feedback in some sort of you own tag - but it'll restricts using one question on several pages or lessons with different jumps). This solution is quite easy to implement, probably an easier way than anyone mentioned there.

You can get problem with some question types using this, but they are easily solved:
* essay - you probably will want to suppress using of manual graded question types in lessons anyway;
*multichoice in several choices mode - you can use correct/partial/incorrect feedbacks;
*match - it lacks feedbacks now, but probably it must have just correct/partial/incorrect as multichoice question, they are needed in it anyway, not only for the lessons.

You may want to use feedback text only as values to communicate with user thought, replacing it in database by subquestion id or code for correct, partial or incorrect values. This allows you to avoid problems with editing feedbacks for existing questions.

''</comment>'' --[[User:Oleg Sychev|Oleg Sychev]] 08:52, 13 November 2008 (CST)

====A new path====

''by [[User:Mark Nielsen|Mark Nielsen]] 13:43, 13 November 2006 (CST)''

After a nice discussion with [http://moodle.org/user/view.php?id=3432&course=5 Michael Penney], a new solution to this problem arose. Instead of working with the current method of each question having a set of defined jumps, instead introduce a new feature called ''state checker'' (the name at the moment, could change later). These ''state checkers'' could be inserted throughout the lesson and are used to determine the navigation. These ''state checkers'' could be set to say, ''if student has more than 70% correct then send the student to location X, otherwise send student to location Y.'' Alternatively, the ''state checker'' could be set to say ''if last question was correct, go to X otherwise go to Y''. These examples are binary, but the ''state checker'', when fully implemented, should allow several more options and more granular control.

'''Pros for this implementation:'''
*No major changes are required to the question bank code.
*Lesson navigation can be controlled via one screen and '''is independent of questions'''.
*More possibilities for lesson navigation control.
*Could reduce the complexity of the multi-stage UI that the other solutions require.
'''Cons:'''
*Migration of old navigation structure could prove to be complicated depending on how the ''state checker'' would be developed (NOTE: this is already a problem. See next section ''Migration of jumps'').

''<comment>''

:If State Checkers are used, then there should be an overall default for how one navigates from one page/question to the next. EG: Correct answer goes to next page in the logical order, Wrong answer goes to same page. Then one adds State Checkers to change the default navigation of the lesson. There should be several configurable default navigations to choose from in the lesson settings.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 16:17, 24 March 2007 (CDT)

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson module#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Comments on questions and jumps===
I think the adaptive jumps of Lesson are a key feature. If I read the above correctly, I don't like limiting this to either a correct answer jump or a wrong answer jump. I do like the concept of a jump form. --[[User:chris collman|chris collman]] 09:49, 8 November 2008 (CST)

This also begs the special navigation features used in clusters and 'branches" with end of Branch which Mark has addressed with [[Development:New_lesson_navigation#Check_Points|Check Points]] which I assume are different that State Checkers.I know nothing about elegance, and that is why I like to write about what developers have created :)--[[User:chris collman|chris collman]] 09:49, 8 November 2008 (CST)

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson module#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.
:Branch tables are grade neutral. That means neither 0% nor 100% credit for any answers or else it will count towards the grade/score. I do not have a issue with a descriptive page, except I would call it a "Choice page" and make it essentially a grade neutral multiple choice question. This would also allow graphics next to a choice, something not possible with a Branch Table.--[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)
:Branch tables, offer the student choices and description question types do not offer any choices. This is a big difference. Perhaps a description question needs the ever present "continue" choice when it will be imported into Lesson from Question Bank.--[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)
:This could also make importing OOwriter and OOimpress pages easier into Lesson. I am still hopeful that something like the GIFT format will allow pages to be imported and exported from Lesson. With the State checker and [[Development:New_lesson_navigation#Check_Points|Check Points]] kind of concepts, this would make that task easier. Perhaps come up with some standard code to attach a state checker to the page? --[[User:chris collman|chris collman]] 09:33, 8 November 2008 (CST)

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

:See discussion about making branch pages more like description questions in Quiz. Or converting Branch tables to a grade neutral format similar to a multiple choice question, where there are no buttons but graphics are allowed.

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson module|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.
*[[Development:New lesson navigation]]
*[[Development:Lesson Specification]]
*[[Development:Adding blocks to lesson]]

[[Category:Moodle 2.0]]
[[Category:Developer|Adding question types to lesson]]
[[Category:Lesson]]

Development:lib/formslib.php Form Definition

2007-12-14T22:30:11Z

Bushido: Missing $ infront of mform

{{Formslib}}
==definition()==

The definition of the elements to be included in the form, their 'types' (PARAM_*), helpbuttons included, etc is all included in a function you must define in your class 'definition();'

definition() is used to define the elements in the form and '''this definition will be used for validating data submitted as well as for printing the form.''' For select and checkbox type elements only data that could have been selected will be allowed. And only data that corresponds to a form element in the defintion will be accepted as submitted data.

The definition() should include all elements that are going to be used on form, some elements may be removed or tweaked later in definition_after_data(). Please do not create conditional elements in definition(), the definition() should not directly depend on the submitted data.

==Use Fieldsets to group Form Elements==

You use code like this to open a fieldset with a legend.

<pre>
//-------------------------------------------------------------------------------
$mform->addElement('header', 'nameforyourheaderelement', get_string('titleforlegened', 'modulename'));
</pre>

You can't yet nest these visible fieldsets unfortunately. But in fact groups of elements are wrapped in invisible fieldsets.

You close a fieldset with moodle_form's closeHeaderBefore method. You tell closeHeaderBefore the element before you wish to end the fieldset. A fieldset is automatically closed if you open a new one. You need to use this code only if you want to close a fieldset and the subsequent form elements are not to be enclosed by a visible fieldset (they are still enclosed with an invisibe one with no legend) :

<pre>
$mform->closeHeaderBefore('buttonar');
</pre>

==addElement==

Use the addElement method to add a an element to a form. The first few arguments are always the same. The first param is the type of the element to add. The second is the elementname to use which is normally the html name of the element in the form. The third is often the text for the label for the element.

Some examples are below :
===button===

<pre>
$mform->addElement('button', 'intro', get_string("buttonlabel"));
</pre>

A button element. If you want a submit or cancel button see 'submit' element.

===checkbox===
<pre>
$mform->addElement('checkbox', 'ratingtime', get_string('ratingtime', 'forum'));
</pre>
This is a simple checkbox. The third param for this element is the label to display on the left side of the form. You can also supply a string as a fourth param to specify a label that will appear on the right of the element. Checkboxes and radio buttons can be grouped and have individual labels on their right.

====advcheckbox====
<pre>
$mform->addElement('advcheckbox', 'ratingtime', get_string('ratingtime', 'forum'), array(0, 1), array('group' => 1));
</pre>
Similar to the checkbox above, but with a couple of important improvements:

#The 4th parameter is an array of values that will be associated with the checked/unchecked state of the checkbox. With a normal checkbox you cannot choose that value, and in fact an unchecked checkbox will not even be sent with the form data.
#The 5th parameter is a normal $attributes array, normally used to set HTML attributes for the <input> element. However, a special value of 'group' can be given, which will add a class name to the element, and enable its grouping for a [[Development:lib/formslib.php_add_checkbox_controller|checkbox controller]]

===choosecoursefile===
<pre>
$mform->addElement('choosecoursefile', 'mediafile', get_string('mediafile', 'lesson'), array('courseid'=>$COURSE->id));

</pre>

Choose a file from the course files area. The fourth option is a list of options for the element.

<pre>
array('courseid'=>null,\\if it is null (default then use globabl $COURSE
'height'=>500,\\ height of the popup window
'width'=>750, \\ width of the popup window
'options'=>'none');\\options string for the pop up window
\\eg. 'menubar=0,location=0,scrollbars,resizable'

</pre>

===date_selector===
<pre>
$mform->addElement('date_selector', 'assesstimefinish', get_string('to'));
</pre>

This is a date selector. You can select a Day, Month and Year using a group of select boxes. The fourth param here is an array of options. The defaults for the options are :

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true);
</pre>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===date_time_selector===
<pre>
$mform->addElement('date_time_selector', 'assesstimestart', get_string('from'));
</pre>
This is a group of select boxes to select a date (Day Month and Year) and time (Hour and Minute). When submitted, submitted data is processed and a timestamp is passed to $form->get_data(); the fourth param here is an array of options. The defaults for the options are:

<pre>array('startyear'=>1970, 'stopyear'=>2020,
'timezone'=>99, 'applydst'=>true, 'step'=>5);
</pre>

You can override these defaults by supplying an array as fourth param with one or more keys with a value to override the default. You can supply a fifth param of attributes here as well.

===file===

File upload input box with browse button. In the form definition type
<pre>
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
</pre>

after form submission and validation use
<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
...
}
</pre>

If you need advanced settings such as required file, different max upload size or name of uploaded file
<pre>

$this->set_upload_manager(new upload_manager('attachment', true, false, $COURSE, false, 0, true, true, false));
$mform->addElement('file', 'attachment', get_string('attachment', 'forum'));
$mform->addRule('attachment', null, 'required');

</pre>

<pre>
if ($data = $mform->get_data()) {
...
$mform->save_files($destination_directory);
$newfilename = $mform->get_new_filename();
...
}
</pre>

When porting old code it is also possible to use the upload manager directly for processing of uploaded files.

Please note that if using set_upload_manager() it must be before addElement('file',..).

===hidden===
<pre>
$mform->addElement('hidden', 'reply', 'yes');
</pre>

A hidden element. Set the element name (in this case '''reply''') to the stated value (in this case '''yes''').

===htmleditor & format===
<pre>

$mform->addElement('htmleditor', 'text', get_string('choicetext', 'choice'));
$mform->setType('text', PARAM_RAW);
$mform->addRule('text', null, 'required', null, 'client');

$mform->addElement('format', 'format', get_string('format'));
</pre>
You can supply a fourth param to htmleditor of an array of options :

<pre>
array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>65,
'width'=>0,'height'=>0, 'course'=>0);
//options same as print_textarea params
//use rows and cols options to control htmleditor size.
</pre>

===modgrade===
<pre>
$mform->addElement('modgrade', 'scale', get_string('grade'), false);
</pre>
This is a custom element for selecting a grade for any activity module. The fourth argument is whether to include an option for no grade which has a value 0. This select box does include scales. The default is true, include no grade option.

A helpbutton is automatically added.

===password===
<pre>
$mform->addElement('password', 'password', get_string('label'), $attributes);
</pre>

A password element. Fourth param is an array or string of attributes.

===passwordunmask===
{{Moodle 1.9}}
<pre>
$mform->addElement('passwordunmask', 'password', get_string('label'), $attributes);
</pre>

A password element with option to show the password in plaintext. Fourth param is an array or string of attributes.

===radio===
<pre>
$radioarray=array();
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('yes'), 1, $attributes);
$radioarray[] = &MoodleQuickForm::createElement('radio', 'yesno', '', get_string('no'), 0, $attributes);
$mform->addGroup($radioarray, 'radioar', '', array(' '), false);
</pre>

Second param names the radio button and should be the same for each button in the group in order to toggle correctly. Third param would be the label for the form element but is generally ignored as this element will always be in a group which has it's own label. Fourth param is a string, a label to be displayed on the right of the element. The fifth is the value for this radio button. $attributes can be a string or an array of attributes.

===select===
<pre>
$mform->addElement('select', 'type', get_string('forumtype', 'forum'), $FORUM_TYPES, $attributes);
</pre>

The fourth param for this element is an array of options for the select box. The keys are the values for the option and the value of the array is the text for the option. The fifth param $attributes is optional, see text element for description of attributes param.

===selectyesno===
<pre>
$mform->addElement('selectyesno', 'maxbytes', get_string('maxattachmentsize', 'forum'));
</pre>

If you want a yes / no select box this one automatically translates itself and has value 1 for yes and 0 for no.

===static===
<pre>
$mform->addElement('static', 'description', get_string('description', 'exercise'),
get_string('descriptionofexercise', 'exercise', $COURSE->students));

</pre>

This is a static element. It should be used with care it is used to display a static piece of text with a label. The third param is the label and the fourth is the static text itself.

===submit, reset and cancel===

<pre>
//normally you use add_action_buttons instead of this code
$buttonarray=array();
$buttonarray[] = &$mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] = &$mform->createElement('reset', 'resetbutton', get_string('revert'));
$buttonarray[] = &$mform->createElement('cancel');
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
$mform->closeHeaderBefore('buttonar');
</pre>

A 'Submit' type element is a submit type form element which will submit the form. A 'Reset' will not submit the form but will reset any changes the user has made to form contents. A 'Cancel' element cancels form submission. You need to have a branch in your code before you check for get_data() to check if submission has been cancelled with is_cancelled(); See the example on the usage page.

You should name your submit and reset buttons 'submitbutton' and 'resetbutton' or something similar (not 'submit' and 'reset'). This avoids problems in JavaScript of collisions between form element names and names of JavaScript methods of the form object.

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges').

===text===

<pre>
$mform->addElement('text', 'name', get_string('forumname', 'forum'), $attributes);
</pre>
For a simple text element. Your fourth parameter here can be a string or array of attributes for the text element. The following are equivalent :
<pre>
$attributes='size="20"';
$attributes=array('size'=>'20');
</pre>

Generally you are encouraged to use CSS instead of using attributes for styling.

A format element can be used as a format select box. It will be non-selectable if you're using an html editor.

The third param for this element is $useHtmlEditor and it defaults to null in which case an html editor is used if the browser and user profile support it.

===textarea===

<pre>
$mform->addElement('textarea', 'introduction', get_string("introtext", "survey"), 'wrap="virtual" rows="20" cols="50"');
</pre>

A textarea element. If you want an htmleditor use htmleditor element. Fourth element here is a string or array of attributes.

==addGroup==

A 'group' in formslib is just a group of elements that will have a label and will be included on one line.

For example typical code to include a submit and cancel button on the same line :

<pre>
$buttonarray=array();
$buttonarray[] =& $mform->createElement('submit', 'submitbutton', get_string('savechanges'));
$buttonarray[] =& $mform->createElement('submit', 'cancel', get_string('cancel'));
$mform->addGroup($buttonarray, 'buttonar', '', array(' '), false);
</pre>

You use the same arguments for createElement as you do for addElement. Any label for the element in the third argument is normally ignored (but not in the case of the submit buttons above where the third argument is not for a label but is the text for the button).

Here's an example of putting a date_selector (which is itself a group of elements) and a checkbox on the same line, note that you can disable every element in the group using the group name 'availablefromgroup' but it doesn't disable the controlling element the 'availablefromenabled' checkbox:

<pre>
$availablefromgroup=array();
$availablefromgroup[] =& $mform->createElement('date_selector', 'availablefrom', '');
$availablefromgroup[] =& $mform->createElement('checkbox', 'availablefromenabled', '', get_string('enable'));
$mform->addGroup($availablefromgroup, 'availablefromgroup', get_string('availablefromdate', 'data'), ' ', false);
$mform->disabledIf('availablefromgroup', 'availablefromenabled');

</pre>

==setHelpButton==
<pre>
$mform->setHelpButton('lessondefault', array('lessondefault', get_string('lessondefault', 'lesson'), 'lesson'));
</pre>
First param is an elementname and the second param is an array of params that are passed to helpbutton in weblib.php. Params are :

<pre>
* @param string $page The keyword that defines a help page
* @param string $title The title of links, rollover tips, alt tags etc
* 'Help with' (or the language equivalent) will be prefixed and '...' will be stripped.
* @param string $module Which module is the page defined in
* @param mixed $image Use a help image for the link? (true/false/"both")
* @param boolean $linktext If true, display the title next to the help icon.
* @param string $text If defined then this text is used in the page, and
* the $page variable is ignored.
* @param boolean $return If true then the output is returned as a string, if false it is printed to the current page.
* @param string $imagetext The full text for the helpbutton icon. If empty use default help.gif
</pre>
Make sure you don't set boolean $return to false.

You need to do use this method after addElement();

==setDefault==

<pre>
$mform->addElement('select', 'grade', get_string('gradeforsubmission', 'exercise'), $grades);
$mform->setHelpButton('grade', array('grade', get_string('gradeforsubmission', 'exercise'), 'exercise'));
$mform->setDefault('grade', 100);
</pre>

Set the default of the form value with setDefault($elementname, $value); where elementname is the elementname whose default you want to set and $value is the default to set. We set the defaults for the form in definition(). This default is what is used if no data is loaded into the form with set_data(); eg. on display of the form for an 'add' rather than 'update' function.

==disabledIf==

For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

You can use $mform->disabledIf($elementName, $dependentOn, $condition = 'notchecked', $value=null)

* elementname can be a group. If you specify a group all elements in the group will be disabled (if dependentOn is in elementname group that is ignored and not disabled). These are the element names you've used as the first argument in addElement or addGroup.
* dependentOn is the actual name of the element as it will appear in html. This can be different to the name used in addGroup particularly but also addElement where you're adding a complex element like a date_selector. Check the html of your page. You typically make the depedentOn a checkbox or select box.
* $condition will be notchecked, checked, selected, eq or if it is anything else then we test for neq.
* If $condition is eq or neq then we check the value of the dependentOn field and check for equality (==) or nonequality (!=) in js
* If $condition is checked or notchecked then we check to see if a checkbox is checked or not.
* If $condition is selected then we check to see if a particular option is selected from a dropdown list.

''Note: I am not sure this section is complete. I just found and added one missing case, but there may be others--[[User:Tim Hunt|Tim Hunt]] 06:04, 15 October 2007 (CDT)''

==setType==

PARAM_* types are used to specify how a submitted variable should be cleaned. These should be used for get parameters such as id, course etc. which are used to load a page and also with setType(); method. Every form element should have a type specified except select, radio box and checkbox elements, these elements do a good job of cleaning themselves (only specified options are allowed as user input).

===Most Commonly Used PARAM_* Types===

These are the most commonly used PARAM_* types and their proper uses. More types can be seen in moodlelib.php starting around line 100.

* PARAM_CLEAN is deprecated and you should try to use a more specific type.
* PARAM_TEXT should be used for cleaning data that is expected to be plain text. It will strip all html tags. But will still let tags for multilang support through.
* PARAM_NOTAGS should be used for cleaning data that is expected to be plain text. It will strip *all* html type tags. It will still *not* let tags for multilang support through. This should be used for instance for email addresses where no multilang support is appropriate.
* PARAM_RAW means no cleaning whatsoever, it is used mostly for data from the html editor. Data from the editor is later cleaned before display using format_text() function. PARAM_RAW can also be used for data that is validated by some other way or printed by p() or s().
* PARAM_INT should be used for integers.
* PARAM_ACTION is an alias of PARAM_ALPHA and is used for hidden fields specifying form actions.

==References==

* [http://midnighthax.com/quickform.php PEAR HTML QuickForm Getting Started Guide by Keith Edmunds of Midnighthax.com]

[[Category:Formslib]]

Development:Adding blocks to lesson

2007-05-28T08:50:18Z

Bushido:

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson and to reduce the number of lesson settings, which are numerous, then block functionality should be added to lesson.

==Lesson blocks goals==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==
{{Moodle 1.9}}
By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

Added in Moodle 1.9. Please note that the global configuration to disable blocks was not implemented.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

After exploring the code, I found that currently the page API does not support this idea. - [[User:Mark Nielsen|Mark Nielsen]] 18:14, 24 March 2007 (CDT)

==Lesson blocks ==
{{Moodle 1.9}}
To add blocks to lesson, just go to the "Preview" tab and turn block editing on by clicking on the "Blocks editing on" button in the upper right hand corner.
[[Image:Lesson Preview BlocksEditingOn button.JPG|center|thumb|Example of buttons]]

*The only quirk is if you answer a question and are on the feedback screen and then push the "Blocks editing on/off" button, you go back to the question that you just answered.

[[Image:Lesson Blocks pulldown Menu.JPG|center|thumb|Example of pulldown menu in lesson]]

Before you can add blocks, be sure that "Show blocks on module pages" is turned on in the administrative settings area. Hint: search for showblocksonmodpages

[http://moodle.org/mod/forum/post.php?reply=304539 Forum thread by Mark Nielsen, developer]

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.
*Reduce lesson's code base.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Developer|Adding blocks to lesson]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2007-03-24T23:14:43Z

Bushido: /* Sticky blocks */

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson and to reduce the number of lesson settings, which are numerous, then block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==
{{Moodle 1.9}}
By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

Added in Moodle 1.9. Please note that the global configuration to disable blocks was not implemented.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

After exploring the code, I found that currently the page API does not support this idea. - [[User:Mark Nielsen|Mark Nielsen]] 18:14, 24 March 2007 (CDT)

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.
*Reduce lesson's code base.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Developer|Adding blocks to lesson]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2007-03-24T23:12:09Z

Bushido: /* Other blocks */

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson and to reduce the number of lesson settings, which are numerous, then block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==
{{Moodle 1.9}}
By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

Added in Moodle 1.9. Please note that the global configuration to disable blocks was not implemented.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.
*Reduce lesson's code base.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Developer|Adding blocks to lesson]]
[[Category:Lesson]]

Development:New lesson navigation

2007-03-24T21:36:00Z

Bushido: /* Possible uses */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
**If student received 100% of the possible points on the last question, go to ''this'' page. If 99% to 60%, go to ''this'' page. If less than 60%, go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced with Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class more natural. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2007-03-24T21:35:20Z

Bushido: /* Possible uses */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
**If student received 100% of the possible points, go to ''this'' page. If 99% to 60%, go to ''this'' page. If less than 60%, go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced with Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class more natural. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding question types to lesson

2007-03-24T21:17:56Z

Bushido: Added a comment to state checkers solution

{{Moodle 2.0}}
Please note that this page deals with a future version of [[Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).
*migrate lesson navigation.

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

====A new path====

''by [[User:Mark Nielsen|Mark Nielsen]] 13:43, 13 November 2006 (CST)''

After a nice discussion with [http://moodle.org/user/view.php?id=3432&course=5 Michael Penney], a new solution to this problem arose. Instead of working with the current method of each question having a set of defined jumps, instead introduce a new feature called ''state checker'' (the name at the moment, could change later). These ''state checkers'' could be inserted throughout the lesson and are used to determine the navigation. These ''state checkers'' could be set to say, ''if student has more than 70% correct then send the student to location X, otherwise send student to location Y.'' Alternatively, the ''state checker'' could be set to say ''if last question was correct, go to X otherwise go to Y''. These examples are binary, but the ''state checker'', when fully implemented, should allow several more options and more granular control.

'''Pros for this implementation:'''
*No major changes are required to the question bank code.
*Lesson navigation can be controlled via one screen and '''is independent of questions'''.
*More possibilities for lesson navigation control.
*Could reduce the complexity of the multi-stage UI that the other solutions require.
'''Cons:'''
*Migration of old navigation structure could prove to be complicated depending on how the ''state checker'' would be developed (NOTE: this is already a problem. See next section ''Migration of jumps'').

''<comment>''

:If State Checkers are used, then there should be an overall default for how one navigates from one page/question to the next. EG: Correct answer goes to next page in the logical order, Wrong answer goes to same page. Then one adds State Checkers to change the default navigation of the lesson. There should be several configurable default navigations to choose from in the lesson settings.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 16:17, 24 March 2007 (CDT)

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.

[[Category:Moodle 2.0]]
[[Category:Developer|Adding question types to lesson]]
[[Category:Lesson]]

Capabilities/block/quickmail:cansend

2007-03-01T22:05:48Z

Bushido:

If a user has this capability, then s/he can see the Quickmail block in the course and use it to send emails to other users in the same course.

Development:Blocks

2007-01-08T20:10:44Z

Bushido: Fixed example code for the config_global.html (added pre tags)

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@uom.gr)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Blocks_Howto#appendix_b| Appendix B]]).
The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though. Experienced developers and those who just want a reference text should refer to [[Blocks_Howto#appendix_a| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==
Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required. Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.
Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==
To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory <span class="filename">/blocks/simplehtml/</span> and creating a file named <span class="filename">/blocks/simplehtml/block_simplehtml.php</span> which will hold our code. We then begin coding the block:
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
}
The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.
Our class is then given a small method: [[Blocks_Howto#method_init| init]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.
[[Blocks_Howto#variable_title| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Blocks_Howto#section_eye_candy| how to disable the title's display]].
[[Blocks_Howto#variable_version| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data. In our example,
this is certainly the case so we just set [[Blocks_Howto#variable_version| $this->version]] to '''YYYYMMDD00''' and forget about it.
'''UPDATING:''' Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.
== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
It can't get any simpler than that, can it? Let's dissect this method to see what's going on...
First of all, there is a check that returns the current value of [[Blocks_Howto#variable_content| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.
At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it and after seeing it in action come back to continue our tutorial.
== Configure That Out ==
The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:
function instance_allow_config() {
return true;
}
This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: <span class="filename">/blocks/simplehtml/config_instance.html</span> (which has to be named exactly like that). For the moment, copy paste the following into it and save:
<nowiki>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>
<?php use_html_editor(); ?>
</nowiki>
It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our <span class="filename">config_instance.html</span> file as instance configuration data. We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.
You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Blocks_Howto#method_init| init]].
In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Blocks_Howto#appendix_a| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Blocks_Howto#variable_config| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in is configuration data. To do that, find this snippet in <span class="filename">/blocks/simplehtml/block_simplehtml.php</span><nowiki>:</nowiki>

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
and change it to:

$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:
<nowiki>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';</nowiki>
After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

== The Specialists ==
Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?
Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:
<nowiki>
<tr valign="top">
<td align="right"><p><?php print_string('configtitle', 'block_simplehtml'); ?>:</td>
<td><input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" /></td>
</tr>
</nowiki>
We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.
That's not too wierd, if we think back a bit. Do you remember that [[Blocks_Howto#method_init| init]] method, where we set [[Blocks_Howto#variable_title| $this->title]]? We didn't actually change its value from then, and [[Blocks_Howto#variable_title| $this->title]] is definitely not the same as $this->config->title (to Moodle, at least). What we need is a way to update [[Blocks_Howto#variable_title| $this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Blocks_Howto#variable_config| $this->config]] in all methods ''except'' [[Blocks_Howto#method_init| init]]<nowiki>! So what can we do?</nowiki>
Let's pull out another ace from our sleeve, and add this small method to our block class:

function specialization() {
$this->title = $this->config->title;
}
Aha, here's what we wanted to do all along! But what's going on with the [[Blocks_Howto#method_specialization| specialization]] method?
This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Blocks_Howto#method_init| init]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Blocks_Howto#method_specialization| specialization]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==
Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists. However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.
This is indeed possible, and the way to do it is to make sure that after the [[Blocks_Howto#method_get_content| get_content]]<nowiki> method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (''). Moodle performs this check by calling the block's </nowiki>[[Blocks_Howto#method_is_empty| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.
Note that the exact value of the block's title and the presence or absence of a [[Blocks_Howto#method_hide_header| hide_header]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.
== We Are Legion ==
Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

function instance_allow_multiple() {
return true;
}
This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!
There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.
And finally, a nice detail is that as soon as we defined an [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] method, the method [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] that was already defined became obsolete. Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Blocks_Howto#method_instance_allow_config| instance_allow_config]] method now without harm. We had only needed it when multiple instances of the block were not allowed.
== The Effects of Globalization ==
Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with. For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.
This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

function has_config() {
return true;
}
Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file <span class="filename">/blocks/simplehtml/config_global.html</span> which again must be named just so, and copy paste the following into it:

<pre>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict)) echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>
<p><input type="submit" value="<?php print_string('savechanges'); ?>" /></p>
</div>
</pre>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean false) it displays the box as pre-checked (reflecting the current status). Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting. "block_simplehtml_strict" clearly satisfies both requirements.
The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?
Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.
However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.
To round our bag of tricks up, notice that the use of if(!empty($CFG->block_simplehtml_strict)) in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable $CFG->block_simplehtml_strict will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").
Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Blocks_Howto#method_config_save| config_save]], the default implementation of which is as follows:

function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}
else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).
So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?
We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.
Much as we did just before with overriding [[Blocks_Howto#method_config_save| config_save]], what is needed here is overriding the method [[Blocks_Howto#method_instance_config_save| instance_config_save]] which handles the instance configuration. The default implementation is as follows:

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data['text'] = strip_tags($data['text']);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!
Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed. The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?
We will let this part of the tutorial come to a close with the obligatory excercise for the reader: in order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead. (Hint: do that in the [[Blocks_Howto#method_get_content| get_content]] method)
'''UPDATING'''<nowiki>: Prior to version 1.5, the file </nowiki><span class="filename">config_global.html</span> was named simply <span class="filename">config.html</span>. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==
Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.
First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

function hide_header() {
return true;
}
One more note here: we cannot just set an empty title inside the block's [[Blocks_Howto#method_init| init]] method; it's necessary for each block to have a unique, non-empty title after [[Blocks_Howto#method_init| init]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.
Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.
To instruct Moodle about our block's preferred width, we add one more method to the block class:

function preferred_width() {
// The preferred value is in pixels
return 200;
}
This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.
Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we 'll see below).
The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").
To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => 'alert("Mouseover on our block!");'
);
}
will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required). And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Blocks_Howto#method_name| name]] method to make it dynamically match our block's name.

== Authorized Personnel Only ==
It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.
Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.
Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.
The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:
#* The format name for the front page of Moodle is '''site-index'''.
#* The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
#* Even though there is no such page, the format name '''all''' can be used as a catch-all option.
We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":
#* Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
#* The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
#* The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
#* The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

function applicable_formats() {
return array('site' => true);
}
Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to true, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).
For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

function applicable_formats() {
return array('course-view' => true, 'course-view-social' => false);
}
This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

function applicable_formats() {
return array('site-index' => true,
'course-view' => true, 'course-view-social' => false,
'mod' => true, 'mod-quiz' => false);
}
It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.
'''UPDATING:''' Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.
== Lists and Icons ==
In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.
As we have seen so far, blocks of use two properties of [[Blocks_Howto#variable_content| $this->content]]<nowiki>: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.</nowiki>
Instead, Moodle expects such blocks to set two other properties when the [[Blocks_Howto#method_get_content| get_content]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.
In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

class block_my_menu extends block_list {
// The init() method does not need to change at all
}
In addition to making this change, we must of course also modify the [[Blocks_Howto#method_get_content| get_content]] method to construct the [[Blocks_Howto#variable_content| $this->content]] variable as discussed above:

function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" width="16" height="16" alt="" />';

// Add more list items here

return $this->content;
}
To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Blocks_Howto#method_get_content| get_content]] method. Adding the mandatory [[Blocks_Howto#method_init| init]] method as discussed earlier will then give us our first list block in no time!

== Appendix A: Reference ==

This Appendix will discuss the base class '''block_base''' from which all other block classes derive, and present each and every method that can be overridden by block developers in detail. Methods that should '''not''' be overridden are explicitly referred to as such. After reading this Appendix, you will have a clear understanding of every method which you should or could override to implement functionality for your block.

The methods are divided into three categories: those you may use and override in your block, those that you may '''not''' override but might want to use, and those internal methods that should '''neither''' be used '''nor''' overridden. In each category, methods are presented in alphabetical order.

=== Methods you can freely use and override: ===
** <div class="function_title">applicable_formats</div>

function applicable_formats() {
// Default case: the block can be used in courses and site index, but not in activities
return array('all' => true, 'mod' => false);
}
This method allows you to control which pages your block can be added to. Page formats are formulated from the full path of the script that is used to display that page. You should return an array with the keys being page format names and the values being booleans (true or false). Your block is only allowed to appear in those formats where the value is true.
Example format names are: '''course-view''', '''site-index''' (this is an exception, referring front page of the Moodle site), '''course-format-weeks''' (referring to a specific course format), '''mod-quiz''' (referring to the quiz module) and '''all''' (this will be used for those formats you have not explicitly allowed or disallowed).
The full matching rules are:
*** Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
*** The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
*** The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
*** The order that the format names appear does not make any difference.
** <div class="function_title">config_print</div>
<nowiki>
function config_print() {
// Default behavior: print the config_global.html file
// You don't need to override this if you're satisfied with the above
if (!$this->has_config()) {
return false;
}
global $CFG, $THEME;
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot.'/blocks/'. $this->name() .'/config_global.html');
print_simple_box_end();
return true;
}</nowiki>
This method allows you to choose how to display the global configuration screen for your block. This is the screen that the administrator is presented with when he chooses "Settings..." for a specific block. Override it if you need something much more complex than the default implementation allows you to do. However, keep these points in mind:
**# If you save your configuration options in $CFG, you will probably need to use global $CFG; before including any HTML configuration screens.
**# The HTML <input> elements that you include in your method's output will be automatically enclosed in a <form> element. You do not need to worry about where and how that form is submitted; however, you '''must''' provide a way to submit it (i.e., an <input type="submit" />.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">config_save</div>

function config_save($data) {
// Default behavior: save all variables as $CFG properties
// You don't need to override this if you 're satisfied with the above
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
This method allows you to override the storage mechanism for your global configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values. The default implementation saves everything as Moodle $CFG variables.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">get_content</div>

function get_content() {
// This should be implemented by the derived class.
return NULL;
}
This method should, when called, populate the [[Blocks_Howto#variable_content| $this->content]] variable of your block. Populating the variable means:
'''EITHER'''<br />defining $this->content->text and $this->content->footer if your block derives from '''block_base'''. Both of these should be strings, and can contain arbitrary HTML.
'''OR'''<br />defining $this->content->items, $this->content->icons and $this->content->footer if your block derives from '''block_list'''. The first two should be numerically indexed arrays having the exact same number of elements. $this->content->items is an array of strings that can contain arbitrary HTML while $this->content->icons also contains should strings, but those must be fully-qualified HTML <img> tags '''and nothing else'''. $this->content->footer is a string, as above.
If you set ''all'' of these variables to their default "empty" values (empty arrays for the arrays and empty strings for the strings), the block will '''not''' be displayed at all except to editing users. This is a good way of having your block hide itself to unclutter the screen if there is no reason to have it displayed.
Before starting to populate [[Blocks_Howto#variable_content| $this->content]], you should also include a simple caching check. If [[Blocks_Howto#variable_content| $this->content]] is exactly equal to NULL then proceed as normally, while if it is not, return the existing value instead of calculating it once more. If you fail to do this, Moodle will suffer a performance hit.
In any case, your method should return the fully constructed [[Blocks_Howto#variable_content| $this->content]] variable.
** <div class="function_title">has_config</div>

function has_config() {
return false;
}
This method should return a boolean value that denotes whether your block wants to present a configuration interface to site admins or not. The configuration that this interface offers will impact all instances of the block equally.
To actually implement the configuration interface, you will either need to rely on the default [[Blocks_Howto#method_instance_config_print| config_print]] method or override it. The full guide contains [[Blocks_Howto#section_effects_of_globalization| more information on this]].
** <div class="function_title">hide_header</div>

function hide_header() {
//Default, false--> the header is shown
return false;
}
This method should return a boolean value that denotes whether your block wants to hide its header (or title). Thus, if you override it to return true, your block will not display a title unless the current user is in editing mode.
** <div class="function_title">html_attributes</div>

function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.
If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
** <div class="function_title">init</div>

function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
This method must be implemented for all blocks. It has to assign meaningful values to the object variables [[Blocks_Howto#variable_title| $this->title]] and [[Blocks_Howto#variable_version| $this->version]] (which is used by Moodle for performing automatic updates when available).
No return value is expected from this method.
** <div class="function_title">instance_allow_config</div>

function instance_allow_config() {
return false;
}
This method should return a boolean value. True indicates that your block wants to have per-instance configuration, while false means it does not. If you do want to implement instance configuration, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
This method's return value is irrelevant if [[Blocks_Howto#method_instance_allow_multiple| instance_allow_multiple]] returns true; it is assumed that if you want multiple instances then each instance needs its own configuration.
** <div class="function_title">instance_allow_multiple</div>

function instance_allow_multiple() {
// Are you going to allow multiple instances of each block?
// If yes, then it is assumed that the block WILL USE per-instance configuration
return false;
}
This method should return a boolean value, indicating whether you want to allow multiple instances of this block in the same page or not. If you do allow multiple instances, it is assumed that you will also be providing per-instance configuration for the block. Thus, you will need to take some additional steps apart from overriding this method; refer to the full guide for [[Blocks_Howto#section_configure_that_out| more information]].
** <div class="function_title">instance_config_print</div>
<nowiki>
function instance_config_print() {
// Default behavior: print the config_instance.html file
// You don't need to override this if you're satisfied with the above
if (!$this->instance_allow_multiple() && !$this->instance_allow_config()) {
return false;
}
global $CFG, $THEME;

if (is_file($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html')) {
print_simple_box_start('center', '', $THEME->cellheading);
include($CFG->dirroot .'/blocks/'. $this->name() .'/config_instance.html');
print_simple_box_end();
} else {
notice(get_string('blockconfigbad'),
str_replace('blockaction=', 'dummy=', qualified_me()));
}

return true;
}</nowiki>
This method allows you to choose how to display the instance configuration screen for your block. Override it if you need something much more complex than the default implementation allows you to do. Keep in mind that whatever you do output from [[Blocks_Howto#method_instance_config_print| config_print]], it will be enclosed in a HTML form automatically. You only need to provide a way to submit that form.
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">instance_config_save</div>

function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance', 'configdata', base64_encode(serialize($data)),
'id', $this->instance->id);
}
This method allows you to override the storage mechanism for your instance configuration data. The received argument is an associative array, with the keys being setting names and the values being setting values.
The configuration must be stored in the "configdata" field of your instance record in the database so that Moodle can auto-load it when your block is constructed. However, you may still want to override this method if you need to take some additional action apart from saving the data. In that case, you really should do what data processing you want and then call parent::instance_config_save($data) with your new $data array. This will keep your block from becoming broken if the default implementation of instance_config_save changes in the future.
Note that $data does not hold all of the submitted POST data because Moodle adds some hidden fields to the form in order to be able to process it. However, before calling this method it strips the hidden fields from the received data and so when this method is called only the "real" configuration data remain.
If you want to update the stored copy of the configuration data at run time (for example to persist some changes you made programmatically), you should not use this method. The correct procedure for that purpose is to call [[Blocks_Howto#method_instance_config_commit| instance_config_commit]].
You should return a boolean value denoting the success or failure of your method's actions.
** <div class="function_title">preferred_width</div>

function preferred_width() {
// Default case: the block wants to be 180 pixels wide
return 180;
}
This method should return an integer value, which is the number of pixels of width your block wants to take up when displayed. Moodle will try to honor your request, but this is actually up to the implementation of the format of the page your block is being displayed in and therefore no guarantee is given. You might get exactly what you want or any other width the format decides to give you, although obviously an effort to accomodate your block will be made.
Most display logic at this point allocates the maximum width requested by the blocks that are going to be displayed, bounding it both downwards and upwards to avoid having a bad-behaving block break the format.
** <div class="function_title">refresh_content</div>

function refresh_content() {
// Nothing special here, depends on content()
$this->content = NULL;
return $this->get_content();
}
This method should cause your block to recalculate its content immediately. If you follow the guidelines for [[Blocks_Howto#get_content| get_content]], which say to respect the current content value unless it is NULL, then the default implementation will do the job just fine.
You should return the new value of [[Blocks_Howto#variable_content| $this->content]] after refreshing it.
** <div class="function_title">specialization</div>

function specialization() {
// Just to make sure that this method exists.
}
This method is automatically called by the framework immediately after your instance data (which includes the page type and id and all instance configuration data) is loaded from the database. If there is some action that you need to take as soon as this data becomes available and which cannot be taken earlier, you should override this method.
The instance data will be available in the variables [[Blocks_Howto#variable_instance| $this->instance]] and [[Blocks_Howto#variable_config| $this->config]].
This method should not return anything at all.
=== Methods which you should ''not'' override but may want to use: ===
** <div class="function_title">instance_config_commit</div>

function instance_config_commit() {
return set_field('block_instance',
'configdata', base64_encode(serialize($this->config)),
'id', $this->instance->id);
}
This method saves the current contents of [[Blocks_Howto#variable_config| $this->config]] to the database. If you need to make a change to the configuration settings of a block instance at run time (and not through the usual avenue of letting the user change it), just make the changes you want to [[Blocks_Howto#variable_config| $this->config]] and then call this method.
** <div class="function_title">get_content_type</div>

function get_content_type() {
return $this->content_type;
}
This method returns the value of [[Blocks_Howto#variable_content_type| $this->content_type]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_title</div>

function get_title() {
return $this->title;
}
This method returns the value of [[Blocks_Howto#variable_title| $this->title]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">get_version</div>

function get_version() {
return $this->version;
}
This method returns the value of [[Blocks_Howto#variable_version| $this->version]], and is the preferred way of accessing that variable. It is guaranteed to always work, now and forever. Directly accessing the variable is '''not recommended'''<nowiki>; future library changes may break compatibility with code that does so.</nowiki>
** <div class="function_title">is_empty</div>
For blocks that extend class '''block_base'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return(empty($this->content->text) && empty($this->content->footer));
}
For blocks that extend class '''block_list'''<nowiki>:</nowiki>

function is_empty() {
$this->get_content();
return (empty($this->content->items) && empty($this->content->footer));
}
This method returns the a boolean true/false value, depending on whether the block has any content at all to display. Blocks without content are not displayed by the framework.
** <div class="function_title">name</div>

function name() {
static $myname;
if ($myname === NULL) {
$myname = strtolower(get_class($this));
$myname = substr($myname, strpos($myname, '_') + 1);
}
return $myname;
}
This method returns the internal name of your block inside Moodle, without the '''block_''' prefix. Obtaining the name of a block object is sometimes useful because it can be used to write code that is agnostic to the actual block's name (and thus more generic and reusable). For an example of this technique, see the [[Blocks_Howto#method_config_print| config_print]] method.
=== Methods which you should ''not'' override and ''not'' use at all: ===
** <div class="function_title">_self_test</div>
This is a private method; no description is given.
** <div class="function_title">_add_edit_controls</div>
This is a private method; no description is given.
** <div class="function_title">_load_instance</div>
This is a private method; no description is given.
** <div class="function_title">_print_block</div>
This is a private method; no description is given.
** <div class="function_title">_print_shadow</div>
This is a private method; no description is given.

The class '''block_base''' also has a few standard member variables which its methods manipulate. These variables, the purpose of each and the type of data they are expected to hold is explained in the next section of this Appendix.

=== Class variables: ===

* <div class="variable_title">$this->config</div>
This variable holds all the specialized instance configuration data that have been provided for this specific block instance (object). It is an object of type stdClass, with member variables directly corresponding to the HTML <input> elements in the block's <span class="filename">config_instance.html</span> file.
The variable is initialized just after the block object is constructed, immediately before [[Blocks_Howto#method_specialization| specialization]] is called for the object. It is possible that the block has no instance configuration, in which case the variable will be NULL.
It is obvious that there is a direct relationship between this variable and the configdata field in the mdl_block_instance table. However, it is ''strongly'' advised that you refrain from accessing the configdata field yourself. If you absolutely must update its value at any time, it is recommended that you call the method [[Blocks_Howto#method_instance_config_commit| instance_config_commit]] to do the actual work.
* <div class="variable_title">$this->content_type</div>
This variable instructs Moodle on what type of content it should assume the block has, and is used to differentiate text blocks from list blocks. It is essential that it has a meaningful value, as Moodle depends on this for correctly displaying the block on screen. Consequently, this variable is closely tied with the variable [[Blocks_Howto#variable_content| $this->content]]. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
The only valid values for this variable are the two named constants [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]] and [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]].
* <div class="variable_title">$this->content</div>
This variable holds all the actual content that is displayed inside each block. Valid values for it are either NULL or an object of class stdClass, which must have specific member variables set as explained below. Normally, it begins life with a value of NULL and it becomes fully constructed (i.e., an object) when [[Blocks_Howto#method_get_content| get_content]] is called.
After it is fully constructed, this object is expected to have certain properties, depending on the value of [[Blocks_Howto#variable_content_type| $this->content_type]]. Specifically:
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_text| BLOCK_TYPE_TEXT]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''text'''</div>This is a string of arbitrary length and content. It is displayed inside the main area of the block, and can contain HTML.
*** <div>'''footer'''</div>This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
** If [[Blocks_Howto#variable_content_type| $this->content_type]] is [[Blocks_Howto#constant_block_type_list| BLOCK_TYPE_LIST]], then [[Blocks_Howto#variable_content| $this->content]] is expected to have the following member variables:
*** <div>'''items'''</div>This is a numerically indexed array of strings which holds the title for each item in the list that will be displayed in the block's area. Since usually such lists function like menus, the title for each item is normally a fully qualified HTML <a> tag.
*** <div>'''icons'''</div>This is a numerically indexed array of strings which represent the images displayed before each item of the list. It therefore follows that it should have the exact number of elements as the items member variable. Each item in this array should be a fully qualified HTML <img> tag.
*** <div>'''footer'''</div>This is a string of arbitrary length and contents. It is displayed below the text, using a smaller font size. It can also contain HTML.
* <div class="variable_title">$this->instance</div>
This member variable holds all the specific information that differentiates one block instance (i.e., the PHP object that embodies it) from another. It is an object of type stdClass retrieved by calling get_record on the table mdl_block_instance. Its member variables, then, directly correspond to the fields of that table. It is initialized immediately after the block object itself is constructed.
* <div class="variable_title">$this->title</div>
This variable is a string that contains the human-readable name of the block. It is used to refer to blocks of that type throughout Moodle, for example in the administrator's block configuration screen and in the editing teacher's add block menu. It is also the title that is printed when the block is displayed on screen, although blocks can specifically change this title to something else if they wish (see below). The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each object.
In the case of blocks which may want to configure their title dynamically through instance configuration, it is still essential to provide a valid title inside [[Blocks_Howto#method_init| init]]. This title may then be overridden when the [[Blocks_Howto#method_specialization| specialization]] method is called by the framework:

function specialization() {
// At this point, $this->instance and $this->config are available
// for use. We can now change the title to whatever we want.
$this->title = $this->config->variable_holding_the_title;
}
* <div class="variable_title">$this->version</div>
This variable should hold each block's version number in the form '''YYYYMMDDXX''', as per the convention throughout Moodle. The version number is used by Moodle to detect when a block has been upgraded and it consequently needs to run the block's upgrade code to bring the "old" version of the block's data up to date. The variable is expected to have a valid value after the framework calls the [[Blocks_Howto#method_init| init]] method for each block.
Most blocks do not keep complex data of their own in the database the way that modules do, so in most cases nothing actually happens during a block version upgrade. However, the version number is displayed in the administration interface for blocks. It is good practice therefore to change your block's version number when it gains new functionality or receives important bug fixes, to enable site administrators to easily identify the exact version of the block they are working with.

Appearing throughout the code related to the Blocks API, there is a number of predefined constants that are utilized to avoid the use of "magic numbers" in the code. These constants are:

=== Named constants: ===

* <div class="named_constant">BLOCK_TYPE_LIST</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].
* <div class="named_constant">BLOCK_TYPE_TEXT</div>
This is one of the two valid values for the [[Blocks_Howto#variable_content_type| $this->content_type]] member variable of every block. Its value specifies the exact requirements that Moodle will then have for [[Blocks_Howto#variable_content| $this->content]].

== Appendix B: Differences in the Blocks API for Moodle versions prior to 1.5 ==

This Appendix will discuss what changes in the Blocks API were introduced by Moodle 1.5 and what steps developers need to take to update their blocks to be fully compatible with Moodle 1.5. Unfortunately, with these changes backward compatibility is broken; this means that blocks from Moodle 1.4 will never work with 1.5 and vice versa.

=== Class naming conventions changed ===
In Moodle 1.4, all block classes were required to have a name like '''CourseBlock_something''' and the base class from which the derived was '''MoodleBlock'''. This has changed in Moodle 1.5, to bring the naming conventions in line with other object-oriented aspects of Moodle (for example there are classes enrolment_base, resource_base etc). The new block classes should instead be named like '''block_something''' and derive from '''block_base'''. This means that in order to make a block compatible with Moodle 1.5, you need to change the class definition

class CourseBlock_online_users extends MoodleBlock { ... }
to

class block_online_users extends block_base { ... }
An exception to the above is the special case where the block is intended to display a list of items instead of arbitrary text; in this case the block class must derive from class '''block_list''' instead, like this:

class block_admin extends block_list { ... }

=== Constructor versus init() ===

In Moodle 1.4, in each block class it was mandatory to define a constructor which accepted a course data record as an argument (the example is from the actual Online Users block):

function CourseBlock_online_users ($course) {
$this->title = get_string('blockname','block_online_users');
$this->content_type = BLOCK_TYPE_TEXT;
$this->course = $course;
$this->version = 2004052700;
}
In contrast, Moodle 1.5 does away with the constructor and instead requires you to define an init() method that takes no arguments:

function init() {
$this->title = get_string('blockname','block_online_users');
$this->version = 2004111600;
}
Of course, this leaves you without access to the $course object, which you might actually need. Since that's probably going to be needed inside [[Blocks_Howto#method_get_content| get_content]], the way to retrieve it is by using this code:

$course = get_record('course', 'id', $this->instance->pageid);
If you are going to need access to $course from inside other methods in addition to [[Blocks_Howto#method_get_content| get_content]], you might fetch the $course object inside the [[Blocks_Howto#method_specialization| specialization]] method and save it as a class variable for later use, in order to avoid executing the same query multiple times:

function specialization() {
$this->course = get_record('course', 'id', $this->instance->pageid);
}

=== Blocks with configuration ===
In Moodle 1.4, blocks could only have what are now (in Moodle 1.5) called "global configuration" options, to differentiate from the new "instance configuration" options. If your block has support for configuration, you will need to take these steps:
## Rename your <span class="filename">config.html</span> file to <span class="filename">config_global.html</span>.
## Edit the newly renamed file and completely remove the <form> tag (Moodle now wraps your configuration in a form automatically).
## If you are using any HTML <input> tags other than those that directly affect your configuration (for example, "sesskey"), REMOVE those too (Moodle will add them automatically as required).
## If you have overridden '''print_config''', rename your method to '''config_print'''.
## If you have overridden '''handle_config''', rename your method to '''config_save'''.
=== Blocks with customized applicable formats ===
The correct way to specify the formats you want to allow or disallow your block to exist has been reworked for Moodle 1.5 to take account of the fact that blocks are no longer restricted to just courses. To have a block retain its intended behavior, you must change these format names (array keys in the return value of [[Blocks_Howto#method_applicable_formats| applicable_formats]]) if they are used in your block:
#* '''social''' should become '''course-view-social'''
#* '''topics''' should become '''course-view-topics'''
#* '''weeks''' should become '''course-view-weeks'''
You should also keep in mind that there is now the possibility of blocks being displayed in other pages too, like the introductory page that users see when they enter an activity module. You might therefore need to make the specification for applicable formats more restrictive to keep your block out of pages it is not supposed to be shown in. Also, there are subtle changes to the way that the final decision to allow or disallow a block is made. For the technical details refer to the definition of [[Blocks_Howto#method_applicable_formats| applicable_formats]], and for a more extended example read [[Blocks_Howto#section_authorized_personnel_only| the section dedicated to this subject]].
That's everything; your block will now be ready for use in Moodle 1.5!

[[Category:Developer]]

[[es:Desarrollo de bloques]]

User:Mark Nielsen

2006-12-22T05:04:35Z

Bushido: /* Welcome */

==What I think about==

*[[Adding_question_types_to_lesson | Adding question types to lesson module]]
*[[Development:New lesson navigation | New lesson navigation]]
*[[Development:Adding blocks to lesson | Adding blocks to lesson]]

==See also==

*[http://moodle.org/user/view.php?id=13075&course=5 My Moodle profile page]

Development:Adding blocks to lesson

2006-12-22T03:57:42Z

Bushido:

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson and to reduce the number of lesson settings, which are numerous, then block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==

By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.
*Reduce lesson's code base.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2006-12-22T03:56:32Z

Bushido: /* Conclusion */

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson and to reduce the number of lesson settings, which are numerous, block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==

By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.
*Reduce lesson's code base.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2006-12-22T03:54:03Z

Bushido:

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson and to reduce the number of lesson settings, which are numerous, block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==

By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2006-12-22T03:52:13Z

Bushido: /* Conclusion */

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson display and to reduce the number of lesson settings, which are numerous, block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==

By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

==Conclusion==

Blocks seem to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2006-12-22T03:45:42Z

Bushido: /* Conclusion */

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via the lesson settings, one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, are static and are block like. In order to add greater flexibility to the lesson display and to reduce the number of lesson settings, which are numerous, block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name ''lesson_menu'')
*Media file (block name ''lesson_media_file'')
*Timer (block name ''lesson_clock'')

The settings for these features would be removed from lesson and would be handled by the block configuration interface. Also these features, as blocks, could be more easily expanded. For example:

*''lesson_menu'' could be configurable to include any lesson page or branch table (often requested).
*''lesson_media_file'' could be configurable to display the media file via a pop-up or embedded into the lesson page.
*''lesson_clock'' could be configurable to be a count down timer or as a clock that displays how long a user has been in a lesson (has been requested).

==Other blocks==

By adding block functionality to lesson, other blocks become available to lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that could disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on specific lesson pages. This would allow one to add a sticky block like ''lesson_menu'' to all pages and add another block like the HTML block that would only appear on a single page.

The possibility of using sticky blocks is still ''fuzzy''. It could prove to be difficult to design an interface that works well with the current block API. '''If''' a clean implementation of sticky blocks cannot be found, then all blocks would behave like sticky blocks. Meaning, all pages would have the same blocks.

==Conclusion==

The adoption of blocks seems to suit lesson well. Here are a few key points:
*Lesson would have a more customizable layout.
*Lesson can take advantage of an existing Moodle feature.
*Moodle users can create their own blocks to plug into lesson.
*The number of lesson settings can be reduced.
*More functionality can be added to existing lesson features.

==Author==
[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding blocks to lesson

2006-12-22T03:33:09Z

Bushido: /* Sticky blocks */

Development:Adding blocks to lesson

2006-12-22T03:30:13Z

Bushido: /* Other blocks */

Development:Adding blocks to lesson

2006-12-22T03:23:42Z

Bushido: /* Lesson blocks */

Development:Adding blocks to lesson

2006-12-22T03:15:06Z

Bushido:

Development:Adding blocks to lesson

2006-12-22T03:13:04Z

Bushido: added categories

Development:Adding blocks to lesson

2006-12-22T03:11:27Z

Bushido:

Development:Adding blocks to lesson

2006-12-22T02:17:14Z

Bushido:

Development:Adding blocks to lesson

2006-12-22T02:12:36Z

Bushido:

The lesson module lends itself well to blocks. It already has a three column format same as a course format. Also, via a lesson's settings one can add a left menu, a timer or a link to a media file. All of these are displayed in the left or the right column, but are static.

In order to add greater flexibility to the lesson display and to reduce the number of settings in the lesson settings, which are numerous, block functionality should be added to lesson.

==Lesson blocks==

Lesson features that would be extracted from lesson and placed into blocks would be the following:
*Left menu (block name lesson_menu)
*Media file (block name lesson_media_file)
*Timer (block name lesson_clock)

The settings for these would be removed from the lesson's settings and be handled by the block configuration.

==Other blocks==

By adding block functionality to lesson, other blocks become available for adding to a lesson. Some blocks would not make sense in a lesson like the admin block. To handle this, lesson would have a global configuration that can disable blocks from being added to a lesson. This will help to reduce confusion for lesson authors.

==Sticky blocks==

Sticky blocks could be used to force a block to appear on every lesson page. Then non-sticky blocks would only appear on the page to which it was added. This would allow one to add a sticky block like lesson_menu to all pages and then on a specific page add an HTML block with specific content for that page.

The possibility of using sticky blocks is still fuzzy. It could prove to be difficult to design an interface that works well with the current block API.

==Conclusion==

Adding blocks seems to suit lesson well. By doing so, lesson gains a the following:
*A more flexible layout.
*A new powerful tool: blocks. Users can create their own blocks to plug into lesson.
*The lesson settings will be reduced.

==Author==
[[User:Mark Nielsen|Mark Nielsen]] 20:12, 21 December 2006 (CST)

Development:Developer notes

2006-12-22T01:30:26Z

Bushido: /* Modules and other recognised plugin types */

<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>.</p>

This area is for developers to work on various bits of code and documentation as necessary. Once material has matured it should be linked to from the main [[Development:Developer documentation|Developer documentation]] page.

==Core code==

*[[Other lang issues|Language issues]]
*[[Datalib Notes]]
*[[Application/session variables]]
*[[Roles]]
*[[Filters schema]]
*[[Filterall support]]
*[[Moodle forms library]]
*[[Martin form notes]]
*[[Groups documentation for module developers]]

==Modules and other recognised plugin types==

*[[Forum development|Forum functional upgrade]]
*[[Blogs and forums|Blogs, forums and the nature of discussion]]
*[[Conditional activities]]
*[[Wiki development|Wiki module development]]
*[[Improved Payment Plugin]]
*[[Calculated question development]]
*[[Cleanups required in the quiz and question bank]]
*[[Adding_question_types_to_lesson|Adding question types to lesson module]]
*[[Numerical question units and intervals]]
*[[Development:New lesson navigation | New lesson navigation]]
*[[Development:Adding blocks to lesson | Adding blocks to lesson]]

==Other==

*[[MoodleDocs development]]
*[[Usability]]
*[[Document Management API]]
*[[wikindx|Possible integration of WIKINDX with Moodle]]
*[[simple web services]]
*[[Quiz and quesions community testing day]]
*[[Development:OM Protocol]]

''I split this into three categories becuase the list was getting a bit long.''--[[User:Tim Hunt|Tim Hunt]] 00:34, 17 August 2006 (WST)

[[Category:Developer]]

Development:New lesson navigation

2006-12-14T19:27:15Z

Bushido: /* Advantages */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced with Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class more natural. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:26:27Z

Bushido: /* Changes to the lesson module */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced with Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:25:54Z

Bushido: /* Possible uses */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (random, linear, etc).

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:25:31Z

Bushido: Added another bullet

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.
*Flow change: as described above, this would change the default flow for which the questions are viewed (Random, linear, etc).

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:22:52Z

Bushido: /* Possible uses */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples.
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:22:19Z

Bushido: Added another point

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order.

One might ask though, ''how was the navigation defined for Questions #1 and #2?'' In the lesson settings, one would set the default flow for the lesson. This default flow could be overridden by the Check Points.

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:18:20Z

Bushido:

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all of the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order. Simple, right?

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:17:21Z

Bushido:

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order. Simple, right?

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:15:35Z

Bushido: /* Author */

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer of complication, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order. Simple, right?

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]]

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T19:15:08Z

Bushido: Wrote out a rough draft of the rest of the page

One of the unique features of lesson is its ability to provide different forms of navigation: branching, randomization, linear, etc. The current form for controlling this navigation is via jump definitions that are defined with nearly every question answer or [[Adding_a_branch_table | Branch]] page button. Also, the navigation is defined by using special pages called [[Clusters | Cluster and End of Cluster]]. Lastly, to add yet another layer of complication, one can define specific navigation between Branch and End of Branch pages. With so many options for designing the navigation of the lesson, one can easily get confused and lost. Further, supporting all of these methods becomes a burden at the user support level and at the code base support level. Thus, we must take a step back and look toward a new method that could combine all the above methods, but at the same time provide the possibility to support new navigation innovations.

==Check Points==

For a lack of a better name, "Check Points" could be the solution for which we search. Check Points would be a special place holder within the lesson layout. For example:

Question #1
Question #2
Check Point
Question #3
Question #4

At these Check Points, one could define a change in navigation. So, let's say that before the Check Point, the navigation was set to linear. The student would then see Question #1 followed by Question #2. Once the student came to the Check Point, the navigation could be changed. Let's say the Check Point changes the navigation to random. Thus, after answering Question #2, the student would then see Questions #3 and #4 in random order. Simple, right?

===Possible uses===

Check Points could be used for much more than changing the order in which a student views the questions. Here is an idea list for possible uses:
*Redirect: when a student hits the Check Point, s/he is redirected to another page in the lesson.
*Conditional: best to explain with examples
**If student has a current grade of 60% or more, then go to ''this'' page. Otherwise go to ''this'' page.
**If student answered last question correctly, go to ''this'' page. Otherwise go to ''this'' page.

===Changes to the lesson module===

Here is a quick list of the changes that would take place if Check Points were implemented:
*Jump definitions would be removed from questions.
*Cluster and End of Cluster pages would be replaced with Check Points.
*Branch pages would remain, but End of Branch would be removed. The functionality between Branch and End of Branch pages would be replaced by Check Points.

===Advantages===

*'''Primary:''' this would make the transition to the question type class much more possible. See this [[Adding_question_types_to_lesson#Questions_and_jumps | problem]] with the migration (Note: ''A new path'' section talks about ''state checkers''. ''state checkers'' are the same as Check Points).
*Centralizes the navigation. By using Check Points for navigation, we simplify the process for defining and maintaining a lesson's flow. When one wants to change the navigation, s/he does not have to choose from a myriad of possibilities, s/he would know to add a Check Point.
*Check Points provide possibility for potential growth. When engineering the Check Points, they can be designed to easily support with new navigation innovations.

===Disadvantages===

*Lesson users will have to learn a new form for controlling their lesson's navigation.
*Migration to the use of Check Points would require Lesson users to redefine their lesson's navigation. Although, some aspects of the navigation can be migrated automatically.

===Conclusion===

Check Points would provide a simplification to the design of the lesson yet allow for more advanced learning experiences. A simple example would be if a student is answering all or most of the questions correctly, then the lesson could adapt to a harder set of questions in order to challenge the student (Adaptive Learning). Also Check Points appear to solve the support problem by centralizing the navigation at both the user level and at the code base level.

==Author==

[[User:Mark Nielsen|Mark Nielsen]] 13:15, 14 December 2006 (CST)

[[Category:Future]]
[[Category:Developer]]
[[Category:Lesson]]

Development:New lesson navigation

2006-12-14T18:22:53Z

Bushido: Added intro and first heading

Development:Developer notes

2006-12-14T18:05:46Z

Bushido: Added link to New lesson navigation

<p class="note">'''Note:''' New developer documentation pages should be added to the ''Development namespace'' by typing <code>Development:</code> before the new page name i.e. <code><nowiki>[[Development:New page name]]</nowiki></code>.</p>

This area is for developers to work on various bits of code and documentation as necessary. Once material has matured it should be linked to from the main [[Development:Developer documentation|Developer documentation]] page.

==Core code==

*[[Other lang issues|Language issues]]
*[[Datalib Notes]]
*[[Application/session variables]]
*[[Roles]]
*[[Filters schema]]
*[[Filterall support]]
*[[Moodle forms library]]
*[[Martin form notes]]
*[[Groups documentation for module developers]]

==Modules and other recognised plugin types==

*[[Forum development|Forum functional upgrade]]
*[[Blogs and forums|Blogs, forums and the nature of discussion]]
*[[Conditional activities]]
*[[Wiki development|Wiki module development]]
*[[Improved Payment Plugin]]
*[[Calculated question development]]
*[[Cleanups required in the quiz and question bank]]
*[[Adding_question_types_to_lesson|Adding question types to lesson module]]
*[[Numerical question units and intervals]]
*[[Development:New lesson navigation | New lesson navigation]]

==Other==

*[[MoodleDocs development]]
*[[Usability]]
*[[Document Management API]]
*[[wikindx|Possible integration of WIKINDX with Moodle]]
*[[simple web services]]
*[[Quiz and quesions community testing day]]
*[[Development:OM Protocol]]

''I split this into three categories becuase the list was getting a bit long.''--[[User:Tim Hunt|Tim Hunt]] 00:34, 17 August 2006 (WST)

[[Category:Developer]]

Development:Adding question types to lesson

2006-11-14T01:29:38Z

Bushido: Added another bullet

{{Moodle 2.0}}
Please note that this page deals with a future version of [[Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).
*migrate lesson navigation.

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

====A new path====

''by [[User:Mark Nielsen|Mark Nielsen]] 13:43, 13 November 2006 (CST)''

After a nice discussion with [http://moodle.org/user/view.php?id=3432&course=5 Michael Penney], a new solution to this problem arose. Instead of working with the current method of each question having a set of defined jumps, instead introduce a new feature called ''state checker'' (the name at the moment, could change later). These ''state checkers'' could be inserted throughout the lesson and are used to determine the navigation. These ''state checkers'' could be set to say, ''if student has more than 70% correct then send the student to location X, otherwise send student to location Y.'' Alternatively, the ''state checker'' could be set to say ''if last question was correct, go to X otherwise go to Y''. These examples are binary, but the ''state checker'', when fully implemented, should allow several more options and more granular control.

'''Pros for this implementation:'''
*No major changes are required to the question bank code.
*Lesson navigation can be controlled via one screen and '''is independent of questions'''.
*More possibilities for lesson navigation control.
*Could reduce the complexity of the multi-stage UI that the other solutions require.
'''Cons:'''
*Migration of old navigation structure could prove to be complicated depending on how the ''state checker'' would be developed (NOTE: this is already a problem. See next section ''Migration of jumps'').

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.

[[Category:Future]]
[[Category:Moodle 2.0]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding question types to lesson

2006-11-13T19:43:50Z

Bushido: Added new solution

{{Moodle 2.0}}
Please note that this page deals with a future version of [[Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

====A new path====

''by [[User:Mark Nielsen|Mark Nielsen]] 13:43, 13 November 2006 (CST)''

After a nice discussion with [http://moodle.org/user/view.php?id=3432&course=5 Michael Penney], a new solution to this problem arose. Instead of working with the current method of each question having a set of defined jumps, instead introduce a new feature called ''state checker'' (the name at the moment, could change later). These ''state checkers'' could be inserted throughout the lesson and are used to determine the navigation. These ''state checkers'' could be set to say, ''if student has more than 70% correct then send the student to location X, otherwise send student to location Y.'' Alternatively, the ''state checker'' could be set to say ''if last question was correct, go to X otherwise go to Y''. These examples are binary, but the ''state checker'', when fully implemented, should allow several more options and more granular control.

'''Pros for this implementation:'''
*No major changes are required to the question bank code.
*Lesson navigation can be controlled via one screen and '''is independent of questions'''.
*More possibilities for lesson navigation control.
*Could reduce the complexity of the multi-stage UI that the other solutions require.
'''Cons:'''
*Migration of old navigation structure could prove to be complicated depending on how the ''state checker'' would be developed (NOTE: this is already a problem. See next section ''Migration of jumps'').

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.

[[Category:Future]]
[[Category:Moodle 2.0]]
[[Category:Developer]]
[[Category:Lesson]]

Development:Adding question types to lesson

2006-10-31T05:42:54Z

Bushido: Added my feedback to Tim's solution

Please note that this page deals with a future version of [[Moodle 2.0]].

A regularly discussed topic is that Lesson should use the same [[#Questions_and_jumps|question classes]] as [[Quiz]]. This page is geared toward this goal by explaining the different aspects required to complete this project.--Mark Nielsen

I think this would be a really good idea, and am willing to help--[[User:Tim Hunt|Tim Hunt]], Quiz module/question bank maintainer.

==Project goals==
*(Primary) Implement the [[Question_types|question type classes]] in [[Lesson]].
*(Primary) Reduce Moodle's code base. Instead of Lesson having its own question code, it can now use [[Question_engine|existing code]].
*Simplify Lesson's code. There is a high mix of presentation and logic and some rather confusing algorithms due to the nature of Lesson and how it is organized.

==Primary coding tasks==

===Adding support for question class===
Implement the question class code and the necessary interfaces for adding and editing questions within Lesson. The needed functionality is as follows:
*Printing questions for attempts. ''Should be nothing to do if we are happy with the same presentation for both quiz and lesson''--[[User:Tim Hunt|Tim Hunt]]
*[[Question_engine#Grades|Grading]] the questions. ''Again, should be fine, as long as the question_(attempts|sessions|states) model is flexible enough for the quiz''--[[User:Tim Hunt|Tim Hunt]]
*Provide a method of adding new questions to a Lesson. ''Hopefully question/showbank.php will work for you, perhaps with a few changs.''--[[User:Tim Hunt|Tim Hunt]]
**When adding a question, display questions in course question bank to select from.
***Provide links/tabs for creating new questions.
**After adding a question, provide an interface to define possible jumps (This step may not be needed. Depends on the solution to [[#Questions_and_jumps|the questions and jumps]] problem). ''This will be new work''--[[User:Tim Hunt|Tim Hunt]]

===Changing the attempts logic===
Among other Lesson table changes, one that is the most significant is changing the ''lesson_attempts'' table. Instead of storing one attempt record for every user answer, ''lesson_attempts'' table should store one record per Lesson attempt. The ''question_states'' table will replace the functionality of the original ''lesson_attempts'' table. Since this is changing such a fundamental part of Lesson, almost all of Lesson's code will have to be adapted to the new logic of attempts.

===Fixing code breaks===
By switching to the question class, nearly all of the current Lesson code will be broken and must be replaced or fixed. Here is a quick breakdown of foreseeable code breaks:
*High scores
*[[Lesson_reports|Lesson reports]]
**[[Quiz_reports|Quiz reports]] might provide a jump start(?)
*[[Lesson_module#Pages.2C_questions.2C_answers_and_responses|Page authoring]]
*[[Jumps#Special_jumps|Jump type interpretation algorithms]]
*On-going score
*Progress bar
*Backup/restore
**Rewrite for new table structures
**Add support for restoring Lessons prior question class support
**Add support in the primary backup/restore routines

===Database migration===
Lesson tables need to be removed or changed and their old data needs to be migrated to new tables. Some of this code will be used in the restore process as well. Here is a basic overview of the database migration process:
*migrate ''lesson_pages'' and ''lesson_answer'' content to question tables. Note: this will only be the content, not the logic for ordering Lesson pages or any other Lesson specific data.
*migrate ''lesson_attempts'' to ''question_states''.
*Re-organization of the lesson tables (see [[#New_database_schema|new database schema]]).

==Unsolved problems==
Here are some tricky issues that do not have a solid or obvious solution. Please advise.

===Questions and jumps===
Page [[Jumps|jumps]] determine the flow from one page to another and are a unique feature to Lesson. So, how does one figure out all the necessary jump definitions needed for a question? In Lesson, every answer has a jump, but this solution is not ideal. A multiple choice question for example would have two cases:
*Single answer: a jump must be defined for each answer.
*[[Lesson_module#Multiple_choice.2C_multiple_answer|Multiple answer]]: a jump would be defined for the correct answer and a jump for the wrong answer.

The follow two sections discuss possible solutions, but please feel free to suggest others. When thinking about this problem and perhaps a new solution, remember the primary goals of this project: reduce code size and simplify the Lesson code to make it easier to maintain.

====Invasive solution====
An invasive solution would be to modify the question class code. This is invasive because the introduced code may only be used by Lesson unless it was implemented in such a way that it would be viable for other uses. Some of the foreseeable changes would include the following:
*Add methods to the ''default_questiontype'' class that would handle the default behavior for defining jumps. Default behavior would be two jump definitions: one for correct answers and one for incorrect answers.
*Provide a place to store the defined jumps.
*In each question type, override the default methods in the ''default_questiontype'' class to suite the behavior of the question (optional for each question type).

'''Pros for this implementation:'''
*All question type code is in one place.
*Clean implementation
*Better work-flow for question authoring
'''Cons:'''
*Potentially introduce code that is unusable by other modules, etc.

====Noninvasive solution====
Lesson would extend all question types that to handle jumps. Lesson would have its own ''type'' folder (mod/lesson/type). This ''type'' folder would be organized the same as ''question/type'' directory. Each question type would have its own folder and in that folder a ''questiontype.php''. So, ''mod/lesson/type/{questiontype}/questiontype.php'' where {questiontype} is replaced with each question type name. The ''questiontype.php'' would extend the original question type class and add the necessary methods for handling jumps. The following methods would be added:
*'''print_jump_form:''' accepts the possible jump values from Lesson and then print (or return) the contents of a form. This form would then be presented to the user to define the possible jumps.
*'''process_jump_form:''' accepts the form data from '''print_jump_form''' and organize it. It then returns the organized data so that Lesson can store it.
*'''interpret_jump:''' accepts the user's answer to the question and the returned value from '''process_jump_form'''. This method would determine which jump Lesson should use.
*'''restore_jumps:''' restore the returned value from '''process_jump_form''' during Lesson's restore routine. Returns the restored value so that Lesson can store it.

Example use:

Two jump definitions: correct or incorrect:

*'''print_jump_form''' would return the following form:
Correct answer jump: [drop-down-menu-with-lesson-jumps]
Wrong answer jump: [drop-down-menu-with-lesson-jumps]
*'''process_jump_form''' would accept the POST data from the above form and organize it in an array like this: array('correct' => [lesson-jump-code], 'wrong' => [lesson-jump-code]). Where [lesson-jump-code] is a Lesson page id or jump code from the [drop-down-menu-with-lesson-jumps]. This array would be returned so that Lesson could store it.
*'''interpret_jump''' would accept the students answer and the above array. It would return the [lesson-jump-code] either associated with ''correct'' or ''wrong'' based on the student's answer.
*'''restore_jumps''' would be called during the Lesson restore process and it would return the restored array so that Lesson could store it. Example: if each answer had a jump then the array would be defined like this: array(answerid => [lesson-jump-code] ... ). The ''answerid'' would have to be mapped to the new answerid during the restore process.

'''Pros for this implementation:'''
*Potential Lesson specific code remains in Lesson.
'''Cons:'''
*Work-flow would have an extra step (create question then define jumps).
*Creating new question types is more difficult.

====A middle way====

I (Tim) don't like either of the above two solutions. I don't like excessively lesson specific code in the question types, but it would be really bad if the code for a particular question type was not all in one place.

I think that the solution is to add a new concept: question outcomes. It will take me a couple of paragraphs to explain what I mean with this.

Currently, after a student attempts a question, you get stuff that falls into two categories:
# generic stuff, like the grade (both before and after applying the penalty factor), the penalty factor itself, the classification of the before grade as Correct/Partially Correct/Incorrect, a possible manual comment added by the teacher, the state of the question (saved, graded, manual graded, closed)
# question-type specific stuff, like the data in question_states->answer column, or the feedback that is displayed on-screen.

I think that in the generic stuff category, we need to add the new concept of 'outcome'. This would be what the lesson module uses to select branches, and would probably also be useful to the quiz reports. It would categorise the student's answer into one of a number of categories, and the question type class would need to implement two new methods:

''array of strings'' all_outcomes($question)

''string'' outcome($question, $state)

For multiple-choice (single response) this would return the answer selected. For shortanswer, numerical and calculated, this would return the answer that was matched. The generic implementation in the base class would probably have to just return 'incorrect'/'partiallycorrect'/'correct' (that is the ids of the strings that are looked up in the language file.

The lesson would then need to do branching be specifying where to go for each outcome. It would requre a multi-stage UI (create the question using the standard questionbank code, add the question to the lesson, link up the outcomes to jump targets). However, done well, this could be a very natural UI.

The quiz UI is not perfect, but I think the way it is now: create a question, then add the question to the quiz, then adjust the grade for that question within the quiz, is very natural to use.

''<comment>''

:This sounds like a generalization of the first solution. The question types would provide the options (outcomes) that need jump associations that are defined by lesson. The workflow is far different from what lesson currently has, but it sounds necessary and reasonable.

:It also appears that lesson would be storing the outcome/jump associations, which is fine a long as the outcome does not change with question editing. Not sure how this would work for multi-choice (single response).

:This is why I posted my solutions :) I did not like them either, but I was hoping that they would inspire better solutions. Thank you Tim, I think your solution is much closer to the final solution than mine were.

''</comment>'' - [[User:Mark Nielsen|Mark Nielsen]] 23:42, 30 October 2006 (CST)

====Migration of jumps====
Regardless of implementation, one problem remains: if each question potentially does not have a jump defined for each answer, then how are the currently defined jumps supposed to be migrated to the new question implementation (remember, Lesson questions have one jump defined for each answer regardless if it makes sense at all)? The only solution that comes to mind is to have strict definitions for migration for the following [[Lesson#Types_of_questions_available_within_a_lesson|question types that exist in Lesson]]:
*Multichoice (single and multianswer)
*Matching
*Numerical
*Short Answer
*True/False
*Essay

Note: the use of migration here refers to upgrading old Lessons '''and''' restoring older Lessons.

===Branch tables===
Once a solution for the above problem has been found, I would like to discuss the possibility of replacing the functionality of [[Lesson#Branches_and_branch_tables|branch tables]] with the [[Question_types#Description|description question type]]. Reason for discussing this after a solution has been found is because the solution may influence the outcome to this problem.

==New database schema==

------------------ ------------------
| | | |
| '''course_modules''' | | [[#lesson_default|lesson_default]] |
| | | |
------------------ ------------------
| |
| |
-------------- --------------
| | | |
| [[#lesson|lesson]] |-----------| '''course''' |
| | | |
-------------- --------------
|
| ---------------------- ----------
| | | | |
|------| [[#lesson_high_scores|lesson_high_scores]] |------| '''user''' |
| | | | |
| ---------------------- ----------
| |
| ----------------- |
| | | |
|------| [[#lesson_grades|lesson_grades]] |----------------|
| | | |
| ----------------- |
| |
| ------------------- |
| | |--------------| ---------------------
|------| [[#lesson_attempts|lesson_attempts]] | | |
| | |-------------------| '''question_attempts''' |
| ------------------- | |
| ---------------------
| ----------------
| | |
|------| [[#lesson_pages|lesson_pages]] |
| |
----------------
| ----------------------------- ------------
| | | | |
|------| [[#lesson_question_instances|lesson_question_instances]] |------| '''[[Quiz_database_structure#question|question]]''' |
| | | | |
| ----------------------------- ------------
|
| -------------------
| | |
|------| [[#lesson_branches|lesson_branches]] |
| |
-------------------
*'''Note''': tables in '''bold''' are standard in Moodle and are there only to show relations.

==Table Descriptions==

Key:
*PK = primary key
*FK = foreign key

===lesson===
Primary module table

Fields:
*id: PK
*course: FK to course
*name: Name of the lesson
*practice: Flag for practice lessons
*modattempts
*password: Stores password for password protected lessons
*dependency: FK to [[#lesson|lesson]] table. The lesson that this lesson is dependent upon
*conditions: conditions for the dependency
*grade: Max grade for the lesson
*cusom: custom scoring flag
*ongoing: display on going score flag
*usemaxgrade: use max grade or mean flag
*maxanswers: maximum answers for a question (would only be used by branch tables, remove?)
*maxattempts: number of attempts on a question
*review
*nextpagedefault: default flow control
*minquestions: minimum questions to answer
*maxpages
*time: allowed time in the lesson per attempt
*retake: allow student to retake
*activitylink: FK to course_modules table
*mediafile
*mediaheight: height of pop-up
*mediawidth: width of pop-up
*mediaclose: display close button for media
*slideshow: display branches in slide show mode flag
*width: width of slide show
*height: height of slide show
*bgcolor: background color of slide show
*displayleft: display left menu
*displayleftif: display left menu if student has already completed lesson flag
*progressbar: display progress bar flag
*highscores: high scores
*available: when lesson is available to student
*deadline: when lesson closes to student
*timemodified: last updated

===lesson_default===
Lesson default settings for a course.

Fields:
*same as the lesson table minus the following fields: name, dependency, activity, mediafile, available, deadline, and modified

===lesson_high_scores===
Keep track of the lesson top scores.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*gradeid: FK to [[#lesson_grades|lesson_grades]] table
*nickname: user's nickname

===lesson_grades===
User attempt grades.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*grade: attempt grade
*completed: time of completion

===lesson_attempts===
Lesson attempts by users.

Fields:
*id: PK
*uniqueid: FK to question_sessions table
*lessonid: FK to [[#lesson|lesson]] table
*userid: FK to user table
*path: users path through the lesson (comma separated list of page ids from the [[#lesson_pages|lesson_pages]] table)
*attempt: user's attempt count
*sumgrade: current total for grades
*timestart: starting time of attempt
*timefinish: ending time of attempt
*timemodified: last time updated

===lesson_pages===
All content pages in lesson.

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*prevpageid: FK to [[#lesson_pages|lesson_pages]] table
*nextpageid: FK to [[#lesson_pages|lesson_pages]] table
*type: values include
**branch
**endofbranch
**cluster
**endofcluster
**question
*display: display in left menu flag
*jumps: jumps related to this page
*timemodified: time last updated

===lesson_question_instances===
Store relation between lesson pages that are questions and the question table. (does not exist in moodle 1.6.1 standard)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*questionid: FK to [[Quiz_database_structure#question|question]] table
*grade: point value of the question

===lesson_branches===
Lesson pages that are branch tables. (does not exist in moodle 1.6.1 but there is different set of fields in lesson_branch)

Fields:
*id: PK
*lessonid: FK to [[#lesson|lesson]] table
*pageid: FK to [[#lesson_pages|lesson_pages]] table
*boilerplates: text of branch buttons
*layout: layout of branch buttons

==Discussion==
If you would like to discuss topics on this page, please make a post in the [http://moodle.org/mod/forum/view.php?f=333 lesson forum].

==See also==
*[http://moodle.org/mod/forum/discuss.php?d=42563 Original lesson forum discussion]
*[[Question_engine|Question engine]]
*[[Lesson|Lesson module]]
*[[Quiz database structure#Overview]] - now, at last, with a diagram of the structure in 1.7.

[[Category:Future]]
[[Category:Moodle 2.0]]
[[Category:Developer]]
[[Category:Lesson]]

File:Quickmail-en-blockdisplay-screenshot.jpg

2006-09-30T21:04:05Z

Bushido: Quickmail block added to a course.

Quickmail block added to a course.

Latest release notes

2006-09-23T00:38:00Z

Bushido: Some more items to lesson improvements

{{About Moodle}}

==Moodle 1.7 - development version==
Expected in September, 2006; available as nightly builds or from CVS HEAD. Please do not install on production sites yet.

===Headline features===

* [[Roles]]
:: Permissions based on fine-grained capabilities allow all kinds of roles to be created and assigned in all contexts around Moodle.
* [[XML database schema]]
:: added support for MS-SQL with more databases to come
* [[Unit tests|Unit testing framework]]
:: Making it easier for developers to write test code, which should ultimately lead to a more reliable Moodle.

===Other improvements===

* Improvements to the [[Lesson|Lesson module]]
**Now has a more unified view of lesson screens.
**Teacher editing:
***Collapsed view is formatted more nicely, displays more information regarding each page and allows the creation of new pages.
***Editing is now speedier by replacing 3 second redirect delays with a notification system.
**New feature: display default feedback.
***Default is '''On''' so previous lessons behave as before.
***Description: if no ''response'' is entered for a question answer and this setting is turned '''Off''', then the user skips the feedback page.
**Graceful degrade of JavaScript.
**Several bug fixes.

* Improvements to the [[Quiz|Quiz module]]
:* The teacher can configure comments that are displayed to the student at the end of their attempt, with the comment displayed depending on the student's score.

* Improvements to some core question types
:* All question types can now have some general feedback. This is displayed to all students after they have finished the question (depending on the quiz settings) and does not depend on what response the student gave. Use this to tell the student what the question was about, or link them to more information about the topic it covers.
:* [[Matching question type|Matching]] questions can have extra wrong answers, and work when two questions have the same answer.
:* [[Multiple Choice question type|Multiple Choice]] questions can have feedback for the whole question, as well as specific answers. This is particularly useful for multiple-response questions.
:* [[Numerical question type|Numerical]] questions can have different answers with different precisions and scores. (Previously this was only supported via GIFT import. Now you can edit questions like this.)

==Moodle 1.6.2+==
To be later released as 1.6.3, available as nightly builds or from CVS branch MOODLE_16_STABLE.

===Bug Fixes===

* Fixed growing size of backups - existing backup files are no longer included in backups
*

==Moodle 1.6.2==
12th September, 2006

===Security===
* Fixed handling of uploaded files in Database module
* Module instance id is now properly validated when creating course module object; developers should use get_coursemodule_from_id() to get valid $cm
* Default error reporting level was lowered to 5, E_WARNINGs are no longer displayed on production sites with debug off.
* Multiple problems leading to information leakage fixed in help.php file
* Fixed information leakage from scheduled backups
* Added basic detection of dataroot accessible from Internet, web installer now better suggests dataroot location outside of web file area
* Swf is now disabled by default in Mediaplugin
* forgot_password.php does not allow remote email or username enumeration by default, the old behavior can be enabled by setting protectusernames to No in site configuration
* Undisclosed SQL injections fixed by automatic data conversions in adodb layer
* Theoretical XSS problems fixed in doc/index.php and files/index.php scripts
* Access to tex and algebra files is blocked when filters are disabled
* Request for redirection in jumpto.php protected with sesskey

===Bug Fixes===

* Fixed error when upgrading forum read tracking
* Locales from language packs should finally work - please check your configuration variables and empty the locale field
* Added missing link for course request
* Fixed several glossary problems with non-ascii characters
* Fixed bug where you could not regrade a quiz question where the teacher had added a comment with a ' character.
* Quiz import of BlackBoard V6 files now much more reliable
* Fixed scheduled backups - they were broken in 1.6 and 1.6.1
* Fixed missing guest icons from course listing
* Database sessions respect sessiontimeout setting
* Fixed redirect problems during upgrade resulting in "Table xxx already exists"
* Lesson module: the "(Continue)" no longer displays for 3 seconds after branch tables.
* Lesson module: now properly checks import formats for support.
* Lesson module: feedback is set properly during the import process.
* and many other smaller fixes

===New Features===

* Authorize.net Payment Gateway: Autoconfigures credit card types if the merchant does not accept some types of credit cards

===Known Problems===
* Broken images in published question categories

==Moodle 1.6.1==
20th July, 2006

===Bug Fixes===

* Fixed regression in Turkish locale handling
* Authorize and Paypal enrolment plugin cleanup
* Fixed serious problem with failing Database restore
* Fixed restore of HotPot module containing attempts
* Minor Database module fixes
* National characters in graphs now work for most languages out of the box
* Reviewed and fixed all *nix locale codes in language packs
* Fixed problems when using Resources with Blocks on the frontpage
* Fixed missing events on the first day of month in calendar
* Fixed several problems in Lesson - scores, branch tables, HTML editor issues
* Fixed broken intermodule relinking of absolute paths - please do not use course backups from original 1.6
* PDF byteserving problems caused by incorrect partial content length solved
* Fixed several regressions in handling of multiple groups
* Fixed alphabet problems in Glossary
* Chameleon theme fixes and enhancements
* Fixed all hard coded admin paths
* Fixed moving of course sections
* Fixed grading of Essays in Quiz
* Several Quiz regrading problems solved
* Questions are now exported into backupdata directory
* Added workaround for problems when editting two quizes in one browser
* Lots of other Quiz related bugs fixed - thanks Tim!

* Fixed IE unsecure items warning on sites with https login
* Improved cookie test on the login page
* Potential security issue with unzipping maliciously-crafted zip files fixed
* Satinized input parameters in help.php
* Calendar view.php now respects forcelogin setting

* And lots of other minor fixes worth upgrading

===New Features===

* Enhanced frontpage settings - frontpage can now be different for logged in users, changed category list display
* Improved administration page layout
* Possibility to change graph font for all locales - moodledata/lang/default.ttf takes precedence over lib/default.ttf
* Local language packs may also contain default.ttf
* Backported improved lang.php from HEAD
* New config.php option $CFG->allowvisiblecoursesinhiddencategories

===Known Problems===

* Broken images in published question categories
* Small number of sites reports problems with Quiz upgrade - please always do a full database backup before any upgrade!

===Related===

* Third party modules should be already updated for 1.6.x - you must install new versions before UTF-8 migration!
* New integration of phpMyAdmin available - fixes upstream security problems and compatiblility with PHP 5

==Moodle 1.6==
19th June, 2006

NOTE: Moodle 1.6 requires PHP 4.3.0 (or PHP 5.1.0) and MySQL 4.1.16 (4.1.12 if you use latin languages only). Here is more info on [[Upgrading to Moodle 1.6]].

===New features===

* [[UTF-8 migration|Unicode]]
::Moodle is now 100% Unicode, which means any language can be mixed together and an end to a number of problems that different character sets caused us.
* [[MoodleDocs development|Documentation]]
::A new one-stop wiki site for ALL Moodle documentation, including links from Moodle itself
* [[Database module]]
::A new activity module that allows collaborative collection of structured data, useful for many things!
* [[LAMS]]
::Integrated via a course format and an activity module
* [[Blogs]]
::Allows reflection on an ongoing basis. Entries are marked and can be viewed by user, course, group, site etc. Contains first new support for [[Tags]].
* [[Reports]]
::All reports are now centralised under Course reports and Admin reports. New reports can be written as plugins and dropped in very easily. One big new report is the new course-based statistics system from Catalyst.
* [[Questions]]
::A centralized bank of questions with the potential to be (re-)used in a variety of modules.
* [[My Moodle]]
::A dashboard interface that allows an overview for each user of all their courses etc.
* [[Hive integration]]
::This initial integration with Hive allows teachers to upload, browse, search and select [[Resources|resources]] within the external repository.
* [[Multiple groups]]
::Users can be part of multiple groups within a course
* [[IMS content package]] resource type
::Supports the loading of any content package as a resource, with an optional repository for sharing packages between courses.
* [[Course backup|Granularised backup]]
* [[Chameleon|Chameleon theme]]
:: An interactive Moodle theme
* [[Enrolment plugins|Multi enrolment]]
::Moodle's enrolment plugins can be used simultaneously on the same site. Also new [[IMS Enterprise]] enrolment plugin.
*[[Authorize.net Payment Gateway]] enrolment plugin
::New feature called 'Order Review'. Admins and teachers may accept or deny payments before processing the credit card and they can also refund payments after processing the credit card in 'Payment Management' page. Students may view their order details. Address Verification System (AVS) and Scheduled-Capture support added. For 'Manual-Capture' admins are notified 5 days prior to pending orders expiring.
===See also===
*[[:Category:Moodle 1.6|Moodle 1.6 features]]

==Moodle 1.5.4==
21st May, 2006

(Because this release contains important security fixes, we highly advise that sites using any previous version of Moodle upgrade to this version as soon as possible.)

===Various fixes===

'''Security'''
* Improved kses cleaning of html SC#204
* Prevent unwanted password change here SC#225
* Fix for Secunia Advisory SA18267, plus some logging of suspicious activity.
* AdoDB tests cleanup after Secunia Advisory SA18267
* Fixed $cfg->forceloginforprofiles logic SC#207. Backported from HEAD

'''General'''
* Various updates/improvements in the the Environmental Check allowing to check if your server suits future Moodle requirements.
* Bug 4619. Fixed one DB query not following coding rules.
* Bug 4607. Avoid duplication of course shortname on restore.
* Fixed one problem with auto-link filters and frames.
* Important fixes to muti-byte text handling routines.
* Small changes to the installer.
* Bug 3853. Some important improvements in the restore of log actions.
* Bug 4328. Prevent some warnings in the blocks system.
* Bug 4341. Extending multi-lang support to the "jumpto" menu (showed in collapsed mode).
* Added rss_get_url() to 1.5 to help support data module
* Added support for having a linked tab even if it is currently selected.
* RSS Client block: Removed secondary cache. [http://moodle.org/bugs/bug.php?op=show&bugid=4625 Bug 4625]
* Email confirmation now includes lastname. [http://moodle.org/bugs/bug.php?op=show&bugid=4869 Bug 4869]
* Database connection errors can now be reported to an admin. See $CFG->emailconnectionerrors in config-dist.php.
* Metacourses: Fixed a problem with self enrolment in child courses.
* Several MySQL v5 compatibility fixes
* Avoid listing more than 200 courses in my courses block, and course listing pages.
* SCORM: Fixed lesson status skin support
* Skype: Added webstatus icon
* File uploads: Only create a directory if needed, [http://moodle.org/bugs/bug.php?op=show&bugid=4659 bug 4659]
* Admin Block. Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4627 bug 4627]: Hide "change password" link in admin block if the user is restricted. Credits for report & patch go to Joseph Rezeau.
* HTMLArea: Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4562 bug 4562]. Fix posted by sgarcia.
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4626 bug 4626] - weblib.php: $course object conversion error in "print_footer " function
* Messaging: Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4621 bug 4621] errors in MySQL v3.23 with message backup.
* Introducing Admin->Environment to help users assess installed software prior to the 1.6 upgrade
* Course Restore: Now we avoid duplicates. [http://moodle.org/bugs/bug.php?op=show&bugid=4607 Bug 4607]
* Assignment: Guests can no longer submit an online assignment. [http://moodle.org/bugs/bug.php?op=show&bugid=4604 Bug 4604]
* File Downloads: Fixed problems for slow (dial up) clients, and avoid hogging memory when PHP's output compression is on.
* Wiki: Supports initial load of contents from course file area. [http://moodle.org/bugs/bug.php?op=show&bugid=3830 Bug 3830]
* Lesson: Now when a teacher edits a page with the "Edit page contents" button and then saves or cancels, s/he gets redirected back to the lesson navigation. This will help to streamline the editing.
* Activity Modules Block - [http://moodle.org/bugs/bug.php?op=show&bugid=4586 bug 4586]
* Metacourse: Fixes unenrolling [http://moodle.org/bugs/bug.php?op=show&bugid=4541 bug 4541]
* File uploads: Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4533 bug 4533] - Max upload size at course level ignored.
* Enrol/Authorize.net: Added Address Verification System (AVS) support.
* Online Users Block: Limit the number of students displayed.
* Unicode Support: Typo3 Library updated to newest version.
* Course Categories: Fixed courses and subcategories in an invisible category being visible. [http://moodle.org/bugs/bug.php?op=show&bugid=4074 Bug 4074]
* Wiki: Fixed a fatal error updating wiki pages.
* Added autocomplete=off in form tag to avoid browser autocomplete [http://moodle.org/bugs/bug.php?op=show&bugid=4423 bug:4423]
* Password change: Primary administrator password can only be changed by the administraror him/herself.
* Enrol/Authorize.net: Some changes:- allow_internal is not need anymore. Shows two option if enrolment key of course is set.- login_https is required for payment pages. My credit card is important. If you haven't a certificate forgot this module. (security)- Expiry date of credit card is more friendly :).
* User profile: Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4400 bug 4400]
* Removed old THEME variable.
* Added some more CSS hooks for the correctness feedback
* Fix [http://moodle.org/bugs/bug.php?op=show&bugid=4366 bug 4366]
* Makes autologinguest possible at site level
* Micro-increment version number to 2.0.10
* Corrected adjustment of relative URLs in <EMBED> tag
* Merging from HEAD:Fix for [http://moodle.org/bugs/bug.php?op=show&bugid=4371 bug 4371] (also SC#199):Now manually created users with admin privileges and force change passwordcannot change their username with impunity.
* Fix for [http://moodle.org/bugs/bug.php?op=show&bugid=4067 bug 4067] - allow user to update assignment when not yet marked
* Fix for [http://moodle.org/bugs/bug.php?op=show&bugid=4314 bug 4314]
* Fix for [http://moodle.org/bugs/bug.php?op=show&bugid=4206 bug 4206]
* Delayed merge from HEAD - If tablelib is going to do fullname voodoo, allow default sort field to be firstname/lastname
* Log actions must be strored to DB without &print_log() takes care of it! [http://moodle.org/bugs/bug.php?op=show&bugid=3853 Bug 3853]
* Fixes [http://moodle.org/bugs/bug.php?op=show&bugid=4354 bug 4354]
* shorten_text() AFTER format properly. See [http://moodle.org/bugs/bug.php?op=show&bugid=4355 bug 4355]
* Prevent a warning when params is empty. [http://moodle.org/bugs/bug.php?op=show&bugid=4328 Bug 4328]
* Now the section "jumpto" menu (showed in collapse mode), supportsthe multilang filter. [http://moodle.org/bugs/bug.php?op=show&bugid=4341 Bug 4341]
* Print performance info if exists and $CFG->perfdebug is enabled.
* Fix for [http://moodle.org/bugs/bug.php?op=show&bugid=4351 bug 4351]. New parasmeter for get_record_sql to disableauto-added LIMIT (in case we are using our own)
* Solved bug found when trying to backup all users! http://moodle.org/mod/forum/discuss.php?d=27105
* Fixing [http://moodle.org/bugs/bug.php?op=show&bugid=4345 bug 4345]: merging problem when fixing [http://moodle.org/bugs/bug.php?op=show&bugid=4303 bug 4303]
* Mimic changes from "Ought to mention the improved assignment grading!"Merged from HEAD
* Ought to mention the improved assignment grading!
* Fixes [http://moodle.org/bugs/bug.php?op=show&bugid=4086 bug 4086] spelling mistake
* Commenting out gz_handler since it seem to cause problemsmore on http://moodle.org/mod/forum/discuss.php?d=34376

'''Assignment'''
* Fixed bug in "Prevent late submissions", thanks to Samuli, [http://moodle.org/bugs/bug.php?op=show&bugid=4780 bug 4780]

'''Enrolment'''
* Enrolment: Better explanation of flat file enrolment format. Re-formatted the imporved flat file enorlment description
* Auth/LDAP: Better support for ActiveDirectory
* Enrol/Authorize.net: PostgreSQL support and some indexes for speed.
* Authorize.net: Address Verification System (AVS) support added.
* Authorize.net: $CGF->login_https must be ON for payment pages.
* Authorize.net: Shows two forms if the enrolment key of the course is set (internal and authorize forms).
* Authorize.net: IIS https fix. It doesn't recognize empty($_SERVER['HTTPS']) but accepts HTTPS=off.

'''Forum Module'''

* Bug 4355. Solved one visualisation problem in the page showing the list of forums.
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4360 bug 4360]
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4431 bug 4431], affecting site course, added function forum_user_can_view_post in lib.php

'''Glossary Module'''
* Bug 4543, 4713. Fixed some problems with entries and categories containing more than one word in their title.
* Bug 4858. Fixed one problem with formats, not being detected properly.
* Bug 4915. Entrylist format now displays the "Send Ratings" button.

'''Hotpot Module'''
* Add support for HP5 quizzes (including JBC and old JQuiz)
* Removed weighting from questiontext in JCloze import
* Fixed import of JCloze into quiz module as a MULTIANSWER question
* Fixed bug in restoring attempts from backup

'''Lesson Module
* Lesson: $navigation and $grade_value were undefined when lesson was added to site main page
* Lesson: Lesson Essay Question Can't be Graded when attempt not finished. [http://moodle.org/bugs/bug.php?op=show&bugid=4174 Bug 4174]
* Lesson: Added cancel button. [http://moodle.org/bugs/bug.php?op=show&bugid=4216 Bug 4216] - cancel button
* Lesson: Fixed [http://moodle.org/mod/forum/discuss.php?d=37537 problem with storing the answerid for numerical questions].
* Lesson: Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=1187 bug 1187]

'''Quiz Module'''

* Fixed bug 4250: Added missing percentages to the grade selector
* Fixed bug 4495: Don't apply lateness check when teacher previews
* Fixed bug 4544: Incorrect path to exported files in some language packs
* Fixed bug 4780: Bug in "Prevent late submissions" setting fixed
* Fixed bug 5070: Students can't see quizzes when they are closed
* Turned off regrading of quizzes that have the attemptonlast option set
* A number of other minor interface fixes
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4319 bug 4319]. Thanks to Jaroslav
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4217 bug 4217]
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4829 bug 4829]
* Now we avoid checking for lateness when teacher previews. [http://moodle.org/bugs/bug.php?op=show&bugid=4495 Bug 4495]
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4688 bug 4688]
* [http://moodle.org/mod/forum/discuss.php?d=39548 Rounding errors could lead to "Partially correct" for correct answers]
* Added missing percentages to the grade selector, [http://moodle.org/bugs/bug.php?op=show&bugid=4250 bug 4250]
* Avoid error messages in case $quiz->sumgrades is zero, [http://moodle.org/bugs/bug.php?op=show&bugid=4454 bug 4454]
* [http://moodle.org/mod/forum/discuss.php?d=27730#181773 get_actual_response() method for cloze question type] contributed by Jean-Michel
* Better PostgreSQL support
* Now With Nicer Presentation of Questions
* Summary text shouldn't be cleaned as only entered by teacher.
* Fixed [http://moodle.org/bugs/bug.php?op=show&bugid=4345 bug 4345]. Report performance improvements caused regression with MySQLv3
* Now we turn off browser-based autocomplete. Fixes [http://moodle.org/bugs/bug.php?op=show&bugid=4423 bug 4423] - Short Answer Quiz Q's Saving Form Entries

'''Resource Module'''

* Solved one problem on restore that was causing some links to become corrupted.
* Slightly changes to the delete_instance() function in resources to allow future improvements.
* Resource restore: Solved bug when [http://moodle.org/mod/forum/discuss.php?d=38801 decoding encoded links for resource]

'''Wiki Module'''

* Solved one problem sending double-slashed info to DB.
* Bug 3830. Load of initial content from course file area is now allowed.

==Moodle 1.5.3==

11th November, 2005

(Because this release contains important security fixes, we highly advise that sites using any previous version of Moodle upgrade to this version as soon as possible.)

===A few new things===

* We now have SCORM 1.3 (SCORM 2004) support!
* Much improved Assignment grading interface, including "quick grading" options
* A new Single-Sign-On API is available

===Various fixes===

'''General'''

* Contains warnings when Moodle is used on an PHP configuration known to be insecure
* Contains fixes for some recently reported security problems (see [http://security.moodle.org/ security.moodle.org])
* Backups now runs a lot faster medium/large installs. Many issues fixed in this area
* Listing of directory sizes can be made much faster on Linux/Unix servers, thanks to a performance fix you can enable from Admin->Variables: "path_to_du"
* We now log more meaningful IP addresses when the server or the clients are working behind a proxy
* Fixed some issues with PHP accelerators
* Upgrade scripts have been refined and work much better for PostgreSQL installations
* General PostgreSQL port code cleanup
* Upgrading to 1.5.3 will fix any legacy Journal to Online Assignment upgrade issues
* RSS libraries now support RSS 2.0 categories, see bug 3654
* Better accesibilty in file uploads, see bug 3662
* Better support for site-wide HTTPS, see bug 3848
* We now send away bots (like Googlebot) from that try mangled URLs, see bug 3958
* Better DST support for non-logged-in users
* Better DST support for repeat events in Calendar
* Small fixes to the lesson, choice and grade modules
* Minor CSS improvements to formal_white and orangewhite themes
* Better pagination in course listing and loglive pages
* Fixed an IE-only bug related to HTMLArea content where user-edited tables could float and hide part of the UI.

'''Authentication'''

* Fixes to change password/forgotten password with external auth
* Data fetched from external DB or LDAP is now truncated correctly
* Fixed bug 4305 -- better login block behaviour when using secureforms
* Better support for utf-8 user data from external auth
* LDAP: General fixes covering sync_users script and logging of errors
* LDAP: Fixed bug 3141 - Can't update external data with LDAP authentication
* LDAP: Fixed bug 3992 - LDAP password including a quote does not work - credits go to Kita
* LDAP: Better support for ActiveDirectory.
* LDAP: Fixed bug #3594
* LDAP: Better handling of multi-source field mapping
* LDAP: Fix for using DN as idnumber - thanks fo Jeff Graham - http://moodle.org/mod/forum/discuss.php?d=28840

'''Enrolment and metacourses'''

* Metacourses: Prevent normal users to gain access to meta courses via manual enrolment
* Metacourses: better support for MySQL v3.23.x
* DB: Enrolment lookups now work reliably with Moodle on MySQL and Postgres
* DB: Non-MySQL databases work again as external enrolment databases
* LDAP: Fixed a wrong call to add_teacher in LDAP plugin.
* LDAP: Servers being down or unavailable no longer prevent logins
* LDAP: Course auto-creation works again
* LDAP: Fixed several bugs reported by Jeff Graham and Barron Koralesky -- including bugs 3912 and 3974
* LDAP: We can now bind non-anonymously to LDAP
* Authorize.net: several fixes

'''Resources'''

* Bugfix: Avoid linking to empty or unlinkable activity names

'''Forums'''

* Big and small optimizations to tracking of read/unread messages, specially for PostgreSQL
* Fixed some PostgreSQL bugs
* Some more actions are now supported by backup/restore when processing log records, see bug 3582
* Now message forum RSS feeds are including category data -- useful under some RSS agregators able to group messages, see bug 3654
* Fixed paging on forum search

'''Blocks'''

* Several performance improvements
* Fixes to the upgrade process, including PostgreSQL syntax and lower memory usage
* Brought in several bugfixes from 1.6dev
* Fixed bug 3478: Cannot add RSS feed as course creator
* Fixed bug 3793: Prevent warning message when configuring a glossary_random block in a course which has no glossaries

'''Quiz'''

* Some CSS style fixes
* Better compatibility with themes that contain forms in the headers
* Highlighting of correct answers can now be turned off
* Fixed bug 3986: Too many random questions. (mindforge)
* Fixed missing action icons
* Fixed bug 3899 and removed some 'missing course object' messages
* Fixed bug 3950: Ee-attempt button inconsistency for multi-attempt quizzes
* Fixed bug 3953: Quiz/report.php pagesize can be set to 0, credits to Jean-Michel
* Fixed potential data data corruption bug 3915
* Fixed bug 3884: Quiz correct highlights missing for 2 of 3 options.
* Fix for the Student review highlight doesn't seem to work bug
* Fixed bug 3804: Differences in question types between 1.5 and 1.6
* Fixed bug 3822: don't count previews as attempts
* Fixed bug 3807: Question numbering issue
* Fixes for the item analysis plug-in, assembled by Jean-Michel
* Now we reset the timeout counter to avoid timeouts
* Several improvements contributed by Jean-Michel Vedrine. You can now change the number of attempts per page displayed on screen, and download results to Excel/text file, including detailed grades
* Fixed export bug with non-English languages

'''SCORM'''

* We now support SCORM 1.3 (SCORM 2004)!
* Fixed a bug with next and prev SCO search
* Fixed bugs related to masteryscore
* Fixed a problem in AICC course tracking

'''Wiki'''

* Now paging of older versions is showed and working properly, see bug 3750

'''Filters'''

* Mediaplugin filter now finds multi-line links in HTML code
* Censor filter: Added original word as title to the blacked-out version. The filter can obscure actual important words by mistake (eg Dickens) and there needs to be some way to recover the meaning

==Moodle 1.5.2==

16th July, 2005

=== Various fixes ===

* Journal -> Assignment upgrade now works properly :-/
* Assignment submodules now upgrade as expected
* Various other bugs with new Assignments fixed
* Journal module is now disabled by default on new installations
* Login page is now 100% HTTPS if required
* Various small standard theme tweaks
* Fix for recent matching questions display bug in Quiz
* Language editor no longer creates empty files when not necessary (caused country list bug)
* Fixed some manifest parsing problems in SCORM module
* Multilang filter now deals with pack names that contain numbers
* Files are now force-downloaded (fixes IE problems and some security issues)
* Relinking debugging output is escaped
* Large MP3 player now displays ID3 tags properly again
* Some chat daemon improvements

=== Some new things ===

* Orangewhite theme optimised for use on PDA
* Forum user posts page can be called without userid
* Altavista BabelFish now allowed in as guest when Google is

==Moodle 1.5.1==

8th July, 2005

===Various fixes===

* Several potential security problems solved
* Allowobjectembed setting now works correctly
* Speed problem on IE, caused by tab hover fixed.
* Cut and paste in editor on Firefox has a more helpful warning message
* Fixed a session problem when logged on as admin during upgrade from very old Moodle version
* Fixed editing problem in Main menu of site
* Minor CSS display problems in a few areas were fixed
* Fixed the adding of a single discussion forum
* Fixed Lesson problems with calculating grades, and dates
* Fixed Lesson problems with entering a cluster after a page
* Censor filter was fixed to make it work better with old themes

===Some new things===

* New theme: Wood
* Metal theme updated for 1.5
* Many language updates for most languages, including a new language: Khmer
* Block classes can now run custom code when an instance is created/deleted (this is useful for blocks that need to set up non-trivial data structures)
* Wizard for Calculated Questions in Quiz was rewritten
* Backup/Restore module selection is now improved and much easier
* Backup/Restore module has much improved relinking support, it's now faster and easier to implement in new modules

==Moodle 1.5==

5th June, 2005

Here you can find the release notes of the current stable version of Moodle. '''If you experience any bugs in this release, please report them at [http://moodle.org/bugs moodle.org/bugs] so we can fix them in the next release.'''

=== Headline features ===

* Web pages are compliant with XHTML Transitional 1.0
* Improved '''Accessibility''', aiming for compliance with WAI (W3C), SENDA (UK) and Section 508 (US) criteria.
* Very strong '''new Themes system''', allowing cascading themes, user themes, course themes, with very fine control of every page in Moodle via CSS.
* Integrated '''Messaging''' feature for direct communication between all users in the site, featuring realtime popup windows, notification, email copies, blocking, history, WYSIWYG editor, etc
* Forum read/unread tracking with highlights allows you to see new postings at a glance and to control how these are displayed (per forum, per user or per site).
* New '''Blocks''' system, allowing multiple copies of blocks and better block configuration
* Full support for '''Daylight Savings Time''' in every locality around the globe, so everyone always see the correct local time for all events.
* New '''extended gradebook''' allowing custom weighting of different activities, setting extra grades (or taking out others) and improved display and sorting options
* Users can be required to agree to a '''Site Policy
'''

=== Other major system-wide improvements ===

'''Admin'''

* New "maintenance mode" allows the admin to temporarily disable a site (during upgrades, for example).
* Moodle can automatically download a new list of timezones from moodle.org or elsewhere and install it to the database (Olson files are supported too)
* New version of Moodle MySQL Admin module (available separately)
* New calendar options page provides user interface to configure the behavior of the calendar

'''Authentication'''

* New Shibboleth Support
* New CAS Support
* New PAM Support
* Improved LDAP integration, so that LDAP can now control course creation, group assignments. Increased performance and scalability performing user synchronisation.
* Certain user fields can be locked by the admin when using external authentication
* Improved session handling now detects "crossover" sessions that we have found in some buggy PHP installations and prevents them
* Sessions can now be stored in the database (good for clustered installations!)
* Users can be forced to change their password

'''Files'''

* Standardised file browsing in all areas
* Improved uploading, with support for automated Virus scanning of new documents using ClamAV.
* Slasharguments now work also on IIS (upgrade to PHP 4.3.11 needed for ISAPI)

'''Filters'''

* Standardised filter library makes it trivial to write new filters that require searching and highlighting of text.
* Huge efficiency improvements for complex filters like the Glossary filter
* New Tidy filter uses the W3C Tidy program to (optionally) clean all user-entered texts throughout the site and convert it to valid XHTML code
* Improved censorship filter, now "blacks out" words using styles and uses a word list from the language packs.
* Improved Flash MP3 player, now shows progress bar while downloading and playing
* Improved Multi-language filter is faster, more forgiving of syntax errors, and uses new editor-friendly syntax: <span lang="en"></span>
* Auto-linking filters (glossary, activities) can work to link all the occurrences (old behaviour), once for each text block or only once for the whole page ($CFG->filtermatchonepertext, $CFG->filtermatchoneperpage).
* More text can now be filtered in Moodle, including activity names, headings and other such small texts. This makes it possible to design completely multi-lingual sites in Moodle that fully appears in the user's chosen language.

'''Themes'''

* Modules can provide standard styles
* Themes can override required styles of other themes
* Users and courses can choose their own themes if the admin allows it
* Implementation of tabs interface on many pages
* Modules, Blocks and Languages can define their own standard styles

'''HTML Editor'''

* The toolbuttons offered in the editor toolbar are now configurable by the admin
* Search and Replace text within the editor text area (with optional use of regular expressions)

'''Course management'''

* Transparent Blackboard 5.5 course importing (partial 6.0 support)
* The new meta-courses allow to get users automatically enroled in a general course (the metacourse) when enroled in any of the metacourse-linked courses
* New tool to copy content from a course to other.

'''New blocks'''

* HTML block: allowing to place arbitrary content (text, images links) in any course mainpage
* Remote RSS feed: allows to display external news channels inside a Moodle course
* Glossary Selection: to choose and display content from a Moodle glossary in course mainpage

'''Calendar'''

* Major speed improvements for sites with a large number of courses using groups
* Repeating events can now be modified or deleted all at the same time or separately as before
* New "remember filter settings" preference that allows calendar filters to remember their status between logins

=== Activity module improvements ===

'''Assignment'''

* Completely refactored into a new class-based design, allowing new plugin-assignment types
* New Online Text assignment type that doesn't require files and allows inline comments when grading - this new type effectively replaces the old Journal module
* Vastly improved grading interface for handling large classes
* New configuration options to disable late submission and to e-mail alerts to teachers when students submit new work

'''Chat'''

* Streamlined interface looks smoother, works faster, even without using the optional server daemon
* Blocks can now be added to chat pages (e.g. for additional information)

'''Choice'''

* Rewritten to allow any number of choices
* The number of users per choice can be limited, which allows it to be used as tool for "signing up" to an array of options.
* You can now download the results of the choice to XLS or a TXT file

'''Forum'''

* Powerful new Google-like forum searching tools
* Forum read/unread tracking - unread messages are highlighted on the course page, forum page, discussion listing and the discussion view
* The tracking system may be disabled by teachers/users
* User profiles show all posts by a user, as well as all discussions
* When admins edit user messages, a notice is attached
* Discussion listing shows the last user who posted to each discussion and when it was, with a direct link to that post
* In group-enabled forums the discussion listing shows the group the thread applies to, with a link to the group description page.

'''Glossary'''

* New setting to enable/disable the print view of each glossary.
* New search system looks for words everywhere (instead of doing exact phrase match).
* More information is sent to logs to be able to track activity better.

'''Journal'''

* The Journal module has not changed since 1.4, and is now deprecated. The upgrade procedure will convert all your Journal activities into Online Assignments, and hide all the old Journal activities. If you don't want this to happen, then define this in your config.php: $CFG->noconvertjournals = true;

'''Lesson'''

* Now supports timed Lessons
* Can create practice Lessons (grades are not stored)
* Option for students to view points earned while taking the Lesson
* Allow students to review their answers before submitting the Lesson
* New Slide Show Mode (only branch tables are displayed as slides)
* New Left Menu (for enabled branch tables only)
* Lessons can now be Password Protected
* A Tree View can be used for the Lesson creation screen
* Students can post their high scores
* New option to save a Lesson's settings as defaults for new lessons in the same course
* Can delete a student's attempts
* New page Jumps:
** Previous Page
** Unseen question within a branch
** Random question within a branch
** Unseen question within a cluster
* Added functionality to view Lesson statistics
* New question type: Essay. Teachers can view each essay and write comments, assign a grade, and then email it all to the student
* New question creation interface

'''Quiz'''

* Can handle adaptive questions, i.e., questions that allow the student to interact with them repeatedly within the same quiz attempt and that can change in response to student answers.
* Student can be allowed to try a question again immediately within the same quiz attempt until they get the answer right.
* There is a penalty mechanism that deducts a specified fraction of the mark for each wrong attempt at a question.
* Allows questions rendered and scored externally (e.g., by mathematical assessment engines) to be integrated seamlessly into Moodle quizzes via the RQP web services protocol.
* Is prepared for the handling of IMS QTI questions once web services for these become available.
* New tabbed teacher interface for previewing, editing, and reviewing quizzes.
* New "improved security" mode shows quiz in a separate full-screen window, with many browser features disabled
* Quizzes can be presented to students in several pages. The number of questions per page is selectable by the teacher.
* Blocks can now be added to quiz pages (to show results table, or additional information etc)
* Better and cleaner interface for question selection and management in the database. Selected questions can be added to quiz, moved to other categories or deleted en mass.
* Random questions are now added to the quiz question list with a dedicated button, leaving a cleaner interface at questions database without phantom placeholders
* Final grade can be a fractional number, with teacher-defined decimal figures
* Improved results page with user-selectable display of columns, cleaner sorting and new mark display options
* Questions can be edited with one click from the improved quiz preview and question preview screens.
* Questions can be copied with one click, to allow question variations to be created with ease.
* Revamped question categories structures and editing interface.
* Categories now can contain nested subcategories and can be re-ordered.
* It is possible to select whether questions from categories, and or their subcategories are displayed on the question edit page.
* It is now possible to select whether to add random questions from a parent category alone, or from a parent category and its sub-categories.
* Quiz creators are prevented from changing the question set of quizes that have had student responses.
* Recognition, and rejection, of overlapping/redundant questions has been improved.
* The display of questions in longer quiz categories on the quiz editing page is now paginated.
* New export types - IMS QTI (2.0) and xhtml. Improvements & fixes to others.
* New import type - Hot Potato. Improvements & fixes to others.

'''Scorm'''

* The module is now fully conformant with the SCORM 1.2 standard.
* User result data storage and reporting was improved.
* AICC packages can now be imported.

'''Survey'''

* Graph formatting has been improved (labels are more readable)

'''Wiki'''

* Changes to wiki pages are now monitored and displayed in Recent Activity block
* Several under the hood improvements to backup/restore and other routines that enhance the reliability of wikis

== See also ==

*[[Old releases|1.4.5 release notes]]

[[Category:Core]]
[[Category:Administrator]]

[[pt:Versões do Moodle]]
[[es:Notas de versiones]]
[[fr:Notes de mise à jour]]