Activity completion API - Revision history

Devdocsbot: Protected "Activity completion API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-09-22T13:58:37Z

Protected "Activity completion API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision		Revision as of 13:58, 22 September 2022
(No difference)

Devdocsbot: Update migration status and path

2022-09-22T13:56:06Z

Update migration status and path

← Older revision		Revision as of 13:56, 22 September 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/core/activitycompletion/}}
	{{Moodle_2.0}}		{{Moodle_2.0}}
	{{Note\|There are changes to the completion API introduced in '''Moodle 3.11''' to be incorporated to this page. Please refer to [[Student activity completion]] for details.}}		{{Note\|There are changes to the completion API introduced in '''Moodle 3.11''' to be incorporated to this page. Please refer to [[Student activity completion]] for details.}}

Nmagill: /* Add information about the completion settings to the activities cm_info object */

2022-01-24T14:38:13Z

Add information about the completion settings to the activities cm_info object

← Older revision		Revision as of 14:38, 24 January 2022
Line 82:		Line 82:
	'completionposts'));		'completionposts'));
	As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.		As you can see, I added the '''completionposts''' field (and the others that aren't covered in this example) to the list of fields.

	=== Add information about the completion settings to the activities cm_info object ===		=== Add information about the completion settings to the activities cm_info object ===
	You will need to add information about the custom rules into the activities cm_info object by either adding, or modifying the module_get_coursemodule_info callback<syntaxhighlight lang="php">		{{Moodle 3.3}}You will need to add information about the custom rules into the activities cm_info object by either adding, or modifying the module_get_coursemodule_info callback<syntaxhighlight lang="php">
	/**		/**
	* Add a get_coursemodule_info function in case any forum type wants to add 'extra' information		* Add a get_coursemodule_info function in case any forum type wants to add 'extra' information
Line 131:		Line 130:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	=== Form changes for completion settings ===		=== Form changes for completion settings ===
	When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.		When you have custom completion conditions, you need to add controls to your module's settings form <tt>mod_form.php</tt> so that users can select these conditions. You can add any necessary controls.
Line 263:		Line 261:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	=== Add function returns descriptions for the completion states ===		=== Add function returns descriptions for the completion states ===
	When you create completion conditions, you need to write a function ''module''<tt>_get_completion_active_rule_descriptions</tt> that gives a human readable description of the completion state.		{{Moodle 3.3}}When you create completion conditions, you need to write a function ''module''<tt>_get_completion_active_rule_descriptions</tt> that gives a human readable description of the completion state.

	The input for the method is the cm_info object for that activity.		The input for the method is the cm_info object for that activity.
Line 308:		Line 305:
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	=== Notifying the completion system ===		=== Notifying the completion system ===
	Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.		Finally you need to notify the completion system whenever these values might have changed for a user (in the case of the forum example, whenever somebody adds or deletes a post). The completion system will end up calling the function above - but only if it needs to.

Nmagill: /* Custom completion rules */ Added in documentation on Moodle 3.3 changes to the API

2022-01-24T14:27:57Z

Custom completion rules: Added in documentation on Moodle 3.3 changes to the API

Show changes

Mudrd8mz: Add a note about 3.11 changes

2021-08-06T17:15:04Z

Add a note about 3.11 changes

← Older revision		Revision as of 17:15, 6 August 2021
Line 1:		Line 1:
	{{Moodle_2.0}}		{{Moodle_2.0}}

			{{Note\|There are changes to the completion API introduced in '''Moodle 3.11''' to be incorporated to this page. Please refer to [[Student activity completion]] for details.}}

	Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.		Modules do not need to be changed to support conditional availability, but they do need changing to support the completion system.

Mudrd8mz: Text replacement - "" to ""

2021-07-14T13:05:29Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 13:05, 14 July 2021
Line 155:		Line 155:
	return ['completionpostsgroup'];		return ['completionpostsgroup'];
	}		}
	</~~code~~>		</syntaxhighlight>

	* The function creates a checkbox and a text input field, which is set to accept only numbers.		* The function creates a checkbox and a text input field, which is set to accept only numbers.
Line 175:		Line 175:
	return (!empty($data['completionpostsenabled']) && $data['completionposts'] != 0);		return (!empty($data['completionpostsenabled']) && $data['completionposts'] != 0);
	}		}
	</~~code~~>		</syntaxhighlight>

	* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.		* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.
Line 198:		Line 198:


	You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <syntaxhighlight lang="php">$data</~~code~~> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.		You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <syntaxhighlight lang="php">$data</syntaxhighlight> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.

	Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:		Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:
Line 269:		Line 269:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Notifying the completion system ===		=== Notifying the completion system ===

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:04:53Z
Text replacement - "<code>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:04, 14 July 2021
				
Line 133:
Line 133:
First, the function that adds these controls: First, the function that adds these controls:



<code> <syntaxhighlight lang="php">
/** /**
  * Add elements for setting the custom completion rules.   * Add elements for setting the custom completion rules.
Line 165:
Line 165:
Next, a function for checking whether the user selected this option: Next, a function for checking whether the user selected this option:



<code> <syntaxhighlight lang="php">
/** /**
  * Called during validation to see whether some module-specific completion rules are selected.   * Called during validation to see whether some module-specific completion rules are selected.
Line 198:
Line 198:






You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <code>$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database. You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <syntaxhighlight lang="php">$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.



Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0: Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:
Line 236:
Line 236:
Here's the function for forum (simplified to include only the one completion option): Here's the function for forum (simplified to include only the one completion option):



<code> <syntaxhighlight lang="php">
  /**   /**
   * Obtains the automatic completion state for this forum based on any conditions    * Obtains the automatic completion state for this forum based on any conditions



Mudrd8mz: /* Example */ Fix usage of $DB->get_record() in the example
2017-07-13T22:00:07Z
Example:  Fix usage of $DB->get_record() in the example

				
				
				
				
				
				← Older revision
				Revision as of 22:00, 13 July 2017
				
Line 236:
Line 236:
Here's the function for forum (simplified to include only the one completion option): Here's the function for forum (simplified to include only the one completion option):



<code>
  /**   /**
   * Obtains the automatic completion state for this forum based on any conditions    * Obtains the automatic completion state for this forum based on any conditions
Line 250:
Line 251:
       
      // Get forum details       // Get forum details
      if(!($forum=$DB->get_record('forum',array('id'=>$cm->instance)))) {       $forum = $DB->get_record('forum', array('id' => $cm->instance), '*', MUST_EXIST);
         throw new Exception("Can't find forum {$cm->instance}"); 
     } 
       
      // If completion option is enabled, evaluate it and return true/false         // If completion option is enabled, evaluate it and return true/false  
Line 270:
Line 269:
      }       }
  }   }
</code>



=== Notifying the completion system === === Notifying the completion system ===



Mudrd8mz: /* Example */ Fix missing phpdocs for the completion_rule_enabled() method
2017-07-13T21:40:06Z
Example:  Fix missing phpdocs for the completion_rule_enabled() method

				
				
				
				
				
				← Older revision
				Revision as of 21:40, 13 July 2017
				
Line 165:
Line 165:
Next, a function for checking whether the user selected this option: Next, a function for checking whether the user selected this option:



  function completion_rule_enabled($data) { <code>
     return (!empty($data['completionpostsenabled']) && $data['completionposts']!=0); /**
 }   * Called during validation to see whether some module-specific completion rules are selected.
 *
 * @param array $data Input data not yet validated.
 * @return bool True if one or more rules is enabled, false if none are.
 */
public function completion_rule_enabled($data) {
    return (!empty($data['completionpostsenabled']) && $data['completionposts'] != 0);
}
</code>



* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero. * The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.



Mudrd8mz: /* Example */ Fix example of add_completion_rules() - remove legacy setHelpButton() and modernise the coding style a bit (not actually tested)
2017-07-13T21:28:20Z
Example:  Fix example of add_completion_rules() - remove legacy setHelpButton() and modernise the coding style a bit (not actually tested)

				
				
				
				
				
				← Older revision
				Revision as of 21:28, 13 July 2017
				
Line 133:
Line 133:
First, the function that adds these controls: First, the function that adds these controls:



  function add_completion_rules() { <code>
     $mform =& $this->_form; /**
  * Add elements for setting the custom completion rules.
     $group=array();   *  
     $group[] =& $mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts','forum'));  * @category completion
     $group[] =& $mform->createElement('text', 'completionposts', ' ', array('size'=>3));  * @return array List of added element names, or names of wrapping group elements.
     $mform->setType('completionposts',PARAM_INT);  */
     $mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), array(' '), false); public function add_completion_rules() {
     $mform->setHelpButton('completionpostsgroup', array('completion', get_string('completionpostshelp', 'forum'), 'forum'));  
     $mform->disabledIf('completionposts','completionpostsenabled','notchecked');     $mform = $this->_form;
  
     return array('completionpostsgroup');     $group = [
 }         $mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts', 'forum')),
        $mform->createElement('text', 'completionposts', ' ', ['size' => 3]),
    ];
    $mform->setType('completionposts', PARAM_INT);
    $mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), [' '], false);
    $mform->addHelpButton('completionpostsgroup', 'completionposts', 'forum');
    $mform->disabledIf('completionposts', 'completionpostsenabled', 'notchecked');
 
    return ['completionpostsgroup'];
}
</code>



* The function creates a checkbox and a text input field, which is set to accept only numbers. * The function creates a checkbox and a text input field, which is set to accept only numbers.

← Older revision		Revision as of 13:04, 14 July 2021
Line 133:		Line 133:
	First, the function that adds these controls:		First, the function that adds these controls:

	<~~code~~>		<syntaxhighlight lang="php">
	/**		/**
	* Add elements for setting the custom completion rules.		* Add elements for setting the custom completion rules.
Line 165:		Line 165:
	Next, a function for checking whether the user selected this option:		Next, a function for checking whether the user selected this option:

	<~~code~~>		<syntaxhighlight lang="php">
	/**		/**
	* Called during validation to see whether some module-specific completion rules are selected.		* Called during validation to see whether some module-specific completion rules are selected.
Line 198:		Line 198:


	You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <~~code~~>$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.		You may have noticed the 'completionunlocked' check. When some users have already completed the activity, the completion settings are 'locked'; they are disabled and cannot be edited, so there will be no value set for those fields in the <syntaxhighlight lang="php">$data</code> object. Normally this will automatically work but when dealing with checkboxes you need to include a check for the 'completionunlocked' value before doing anything that would cause one of those fields to be changed in the database.

	Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:		Finally, forum already had a <tt>data_preprocessing</tt> function but I added code to this to set up the checkboxes when the form is displayed, and to make the default value of the text fields 1 instead of 0:
Line 236:		Line 236:
	Here's the function for forum (simplified to include only the one completion option):		Here's the function for forum (simplified to include only the one completion option):

	<~~code~~>		<syntaxhighlight lang="php">
	/**		/**
	* Obtains the automatic completion state for this forum based on any conditions		* Obtains the automatic completion state for this forum based on any conditions

← Older revision		Revision as of 22:00, 13 July 2017
Line 236:		Line 236:
	Here's the function for forum (simplified to include only the one completion option):		Here's the function for forum (simplified to include only the one completion option):

			<code>
	/**		/**
	* Obtains the automatic completion state for this forum based on any conditions		* Obtains the automatic completion state for this forum based on any conditions
Line 250:		Line 251:

	// Get forum details		// Get forum details
	~~if(!(~~$forum=$DB->get_record('forum',array('id'=>$cm->instance)~~))) {~~		$forum = $DB->get_record('forum', array('id' => $cm->instance), '*', MUST_EXIST);
	~~throw new Exception("Can~~'~~t find forum {$cm->instance}"~~);
	}

	// If completion option is enabled, evaluate it and return true/false		// If completion option is enabled, evaluate it and return true/false
Line 270:		Line 269:
	}		}
	}		}
			</code>

	=== Notifying the completion system ===		=== Notifying the completion system ===

← Older revision		Revision as of 21:40, 13 July 2017
Line 165:		Line 165:
	Next, a function for checking whether the user selected this option:		Next, a function for checking whether the user selected this option:

	function completion_rule_enabled($data) {		<code>
	return (!empty($data['completionpostsenabled']) && $data['completionposts']!=0);		/**
	}		* Called during validation to see whether some module-specific completion rules are selected.
			*
			* @param array $data Input data not yet validated.
			* @return bool True if one or more rules is enabled, false if none are.
			*/
			public function completion_rule_enabled($data) {
			return (!empty($data['completionpostsenabled']) && $data['completionposts'] != 0);
			}
			</code>

	* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.		* The custom completion rule is enabled if the 'enabled' checkbox is ticked and the text field value is something other than zero.

← Older revision		Revision as of 21:28, 13 July 2017
Line 133:		Line 133:
	First, the function that adds these controls:		First, the function that adds these controls:

	function add_completion_rules() {		<code>
	$mform =& $this->_form;		/**
			* Add elements for setting the custom completion rules.
	$group=~~array();~~		*
	~~$group[] =&~~ $mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts','forum'));		* @category completion
	~~$group[] =&~~ $mform->createElement('text', 'completionposts', ' ', ~~array(~~'size'=>3));		* @return array List of added element names, or names of wrapping group elements.
	$mform->setType('completionposts',PARAM_INT);		*/
	$mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), ~~array(~~' '), false);		public function add_completion_rules() {
	$mform->~~setHelpButton~~('completionpostsgroup', ~~array(~~'~~completion', get_string('completionpostshelp~~', 'forum'~~), 'forum')~~);
	$mform->disabledIf('completionposts','completionpostsenabled','notchecked');		$mform = $this->_form;

	return ~~array(~~'completionpostsgroup');		$group = [
	}		$mform->createElement('checkbox', 'completionpostsenabled', ' ', get_string('completionposts', 'forum')),
			$mform->createElement('text', 'completionposts', ' ', ['size' => 3]),
			];
			$mform->setType('completionposts', PARAM_INT);
			$mform->addGroup($group, 'completionpostsgroup', get_string('completionpostsgroup','forum'), [' '], false);
			$mform->addHelpButton('completionpostsgroup', 'completionposts', 'forum');
			$mform->disabledIf('completionposts', 'completionpostsenabled', 'notchecked');

			return ['completionpostsgroup'];
			}
			</code>

	* The function creates a checkbox and a text input field, which is set to accept only numbers.		* The function creates a checkbox and a text input field, which is set to accept only numbers.