Persistent form - Revision history

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


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

				
				
				
				
				
				← Older revision
				Revision as of 13:38, 14 July 2021
				
Line 7:
Line 7:
In order for the form class to know what persistent we'll be dealing with, we must declare the ''protected static $persistentclass'' variable. The latter contains the fully qualified name of the persistent class. In order for the form class to know what persistent we'll be dealing with, we must declare the ''protected static $persistentclass'' variable. The latter contains the fully qualified name of the persistent class.



<code php> <syntaxhighlight lang="php">
/** @var string Persistent class name. */ /** @var string Persistent class name. */
protected static $persistentclass = 'example\\status'; protected static $persistentclass = 'example\\status';
Line 16:
Line 16:
Unfortunately this is not automatically done for us, so let's add our fields to the ''definition()'' method like you would do for any form. Unfortunately this is not automatically done for us, so let's add our fields to the ''definition()'' method like you would do for any form.



<code php> <syntaxhighlight lang="php">
/** /**
  * Define the form.   * Define the form.
Line 51:
Line 51:
Secondly, the persistent instance must be provided to the form through the custom data. That persistent instance will be used to populate the form with initial data, typically when you are editing an object. When you don't have a persistent instance yet, probably because your user will be creating a new one, then simply pass null. Secondly, the persistent instance must be provided to the form through the custom data. That persistent instance will be used to populate the form with initial data, typically when you are editing an object. When you don't have a persistent instance yet, probably because your user will be creating a new one, then simply pass null.



<code php> <syntaxhighlight lang="php">
$customdata = [ $customdata = [
     'persistent' => $persistent,  // An instance, or null.      'persistent' => $persistent,  // An instance, or null.
Line 61:
Line 61:
Just like any other form, we will be using ''get_data()'' to validate the form. The only difference is that to determine whether we are editing an object, or creating a new one, we will check if the ''id'' value was returned to us. The persistent form will return the ID value from the persistent we gave it. Then it's up to you to decide how to apply the data, most likely you will defer the logic to another part of your code, one that ensures that all capability checks are fulfilled.   Just like any other form, we will be using ''get_data()'' to validate the form. The only difference is that to determine whether we are editing an object, or creating a new one, we will check if the ''id'' value was returned to us. The persistent form will return the ID value from the persistent we gave it. Then it's up to you to decide how to apply the data, most likely you will defer the logic to another part of your code, one that ensures that all capability checks are fulfilled.  



<code php> <syntaxhighlight lang="php">
// Get the data. This ensures that the form was validated. // Get the data. This ensures that the form was validated.
if (($data = $form->get_data())) { if (($data = $form->get_data())) {
Line 88:
Line 88:
There are times when the built-in validation of the persistent is not enough. Usually you would use the method ''validation()'', but as the form persistent class does some extra stuff to make it easier for you, you must use the ''extra_validation()'' method. The latter works almost just like the ''validation()'' one. There are times when the built-in validation of the persistent is not enough. Usually you would use the method ''validation()'', but as the form persistent class does some extra stuff to make it easier for you, you must use the ''extra_validation()'' method. The latter works almost just like the ''validation()'' one.



<code php> <syntaxhighlight lang="php">
/** /**
  * Extra validation.   * Extra validation.
Line 118:
Line 118:
The fields to remove are never validated and they are not returned when calling ''get_data()''. By default the submit button is added to this list so that when we call ''get_data()'' we only get the persistent-related fields. To remove more fields, re-declare the ''protected static $fieldstoremove'' class variable. The fields to remove are never validated and they are not returned when calling ''get_data()''. By default the submit button is added to this list so that when we call ''get_data()'' we only get the persistent-related fields. To remove more fields, re-declare the ''protected static $fieldstoremove'' class variable.



<code php> <syntaxhighlight lang="php">
/** @var array Fields to remove when getting the final data. */ /** @var array Fields to remove when getting the final data. */
protected static $fieldstoremove = array('submitbutton', 'areyouhappy'); protected static $fieldstoremove = array('submitbutton', 'areyouhappy');
Line 129:
Line 129:
What about when we have a ''legit'' field but it does not belong to the persistent? We still want to validate it ourselves, but we don't want it to be validated by the persistent as it will cause an error. In that case we define it in the ''protected static $foreignfields'' class variable. What about when we have a ''legit'' field but it does not belong to the persistent? We still want to validate it ourselves, but we don't want it to be validated by the persistent as it will cause an error. In that case we define it in the ''protected static $foreignfields'' class variable.



<code php> <syntaxhighlight lang="php">
/** @var array Fields to remove from the persistent validation. */ /** @var array Fields to remove from the persistent validation. */
protected static $foreignfields = array('updatedelay'); protected static $foreignfields = array('updatedelay');
Line 136:
Line 136:
Now the persistent will not validate this field, and we will get the ''updatedelay'' value when we call ''get_data()''. Just don't forget to remove it before you feed the data to your persistent. Now the persistent will not validate this field, and we will get the ''updatedelay'' value when we call ''get_data()''. Just don't forget to remove it before you feed the data to your persistent.



<code php> <syntaxhighlight lang="php">
if (($data = $form->get_data())) { if (($data = $form->get_data())) {
     $updatedelay = $data->updatedelay;      $updatedelay = $data->updatedelay;
Line 152:
Line 152:
First, let's update our persistent with the new two values we will store: First, let's update our persistent with the new two values we will store:



<code php> <syntaxhighlight lang="php">
protected static function define_properties() { protected static function define_properties() {
     ...      ...
Line 171:
Line 171:
Secondly, we must add the group to the form: Secondly, we must add the group to the form:



<code php> <syntaxhighlight lang="php">
public function definition() { public function definition() {
     ...      ...
Line 198:
Line 198:
If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''. If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''.



<code php> <syntaxhighlight lang="php">
/** /**
  * Convert fields.   * Convert fields.
Line 221:
Line 221:
While this works fine, this is not enough as when we load an existing object we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent. While this works fine, this is not enough as when we load an existing object we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent.



<code php> <syntaxhighlight lang="php">
/** /**
  * Get the default data.   * Get the default data.
Line 248:
Line 248:
=== Minimalist === === Minimalist ===



<code php> <syntaxhighlight lang="php">
class status_form extends \core\form\persistent { class status_form extends \core\form\persistent {
             
Line 278:
Line 278:
=== More advanced === === More advanced ===



<code php> <syntaxhighlight lang="php">
class status_form extends \core\form\persistent { class status_form extends \core\form\persistent {



Line 339:
Line 339:
Consider the following code to be a page the users will access at '/example.php'. Consider the following code to be a page the users will access at '/example.php'.



<code php> <syntaxhighlight lang="php">
require 'config.php'; require 'config.php';

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

2021-07-14T13:03:56Z

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

← Older revision		Revision as of 13:03, 14 July 2021
Line 10:		Line 10:
	/** @var string Persistent class name. */		/** @var string Persistent class name. */
	protected static $persistentclass = 'example\\status';		protected static $persistentclass = 'example\\status';
	</~~code~~>		</syntaxhighlight>

	== Defining the form fields ==		== Defining the form fields ==
Line 35:		Line 35:
	$this->add_action_buttons();		$this->add_action_buttons();
	}		}
	</~~code~~>		</syntaxhighlight>

	All of this is pretty standard, except for the ''userid''. When creating a new 'status', we do not want our users to be in control of this value. Therefore we define it as a hidden value which we lock (using ''setConstant'') to the value we created our form with. All the mandatory fields (without a default value) of the persistent need to be added to the form. If your users cannot change their values, then they must be hidden and locked with ''setConstant''.		All of this is pretty standard, except for the ''userid''. When creating a new 'status', we do not want our users to be in control of this value. Therefore we define it as a hidden value which we lock (using ''setConstant'') to the value we created our form with. All the mandatory fields (without a default value) of the persistent need to be added to the form. If your users cannot change their values, then they must be hidden and locked with ''setConstant''.
Line 57:		Line 57:
	];		];
	$form = new status_form($PAGE->url->out(false), $customdata);		$form = new status_form($PAGE->url->out(false), $customdata);
	</~~code~~>		</syntaxhighlight>

	Just like any other form, we will be using ''get_data()'' to validate the form. The only difference is that to determine whether we are editing an object, or creating a new one, we will check if the ''id'' value was returned to us. The persistent form will return the ID value from the persistent we gave it. Then it's up to you to decide how to apply the data, most likely you will defer the logic to another part of your code, one that ensures that all capability checks are fulfilled.		Just like any other form, we will be using ''get_data()'' to validate the form. The only difference is that to determine whether we are editing an object, or creating a new one, we will check if the ''id'' value was returned to us. The persistent form will return the ID value from the persistent we gave it. Then it's up to you to decide how to apply the data, most likely you will defer the logic to another part of your code, one that ensures that all capability checks are fulfilled.
Line 82:		Line 82:
	redirect(new moodle_url('/'));		redirect(new moodle_url('/'));
	}		}
	</~~code~~>		</syntaxhighlight>

	== Additional validation ==		== Additional validation ==
Line 106:		Line 106:
	return $newerrors;		return $newerrors;
	}		}
	</~~code~~>		</syntaxhighlight>

	The typical additional validation will return an array of errors, those will override any previously defined errors. Sometimes, though rarely, you will need to remove previously reported errors, hence the reference to ''$errors'' given, which you can modify directly. Do not abuse it though, this should only be used when you have no other choice.		The typical additional validation will return an array of errors, those will override any previously defined errors. Sometimes, though rarely, you will need to remove previously reported errors, hence the reference to ''$errors'' given, which you can modify directly. Do not abuse it though, this should only be used when you have no other choice.
Line 121:		Line 121:
	/** @var array Fields to remove when getting the final data. */		/** @var array Fields to remove when getting the final data. */
	protected static $fieldstoremove = array('submitbutton', 'areyouhappy');		protected static $fieldstoremove = array('submitbutton', 'areyouhappy');
	</~~code~~>		</syntaxhighlight>

	Do not forget to add the ''submitbutton'' back in there.		Do not forget to add the ''submitbutton'' back in there.
Line 132:		Line 132:
	/** @var array Fields to remove from the persistent validation. */		/** @var array Fields to remove from the persistent validation. */
	protected static $foreignfields = array('updatedelay');		protected static $foreignfields = array('updatedelay');
	</~~code~~>		</syntaxhighlight>

	Now the persistent will not validate this field, and we will get the ''updatedelay'' value when we call ''get_data()''. Just don't forget to remove it before you feed the data to your persistent.		Now the persistent will not validate this field, and we will get the ''updatedelay'' value when we call ''get_data()''. Just don't forget to remove it before you feed the data to your persistent.
Line 142:		Line 142:
	$newpersistent = new status(0, $data);		$newpersistent = new status(0, $data);
	}		}
	</~~code~~>		</syntaxhighlight>

	This method is particularily useful when dealing with file managers.		This method is particularily useful when dealing with file managers.
Line 167:		Line 167:
	...		...
	}		}
	</~~code~~>		</syntaxhighlight>

	Secondly, we must add the group to the form:		Secondly, we must add the group to the form:
Line 194:		Line 194:
	...		...
	}		}
	</~~code~~>		</syntaxhighlight>

	If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''.		If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''.
Line 215:		Line 215:
	return $data;		return $data;
	}		}
	</~~code~~>		</syntaxhighlight>

	Now it works because we've converted our group to individual properties. Note that you must call the parent method because we're automatically doing the same thing for you when you're using a text editor field.		Now it works because we've converted our group to individual properties. Note that you must call the parent method because we're automatically doing the same thing for you when you're using a text editor field.
Line 240:		Line 240:
	return $data;		return $data;
	}		}
	</~~code~~>		</syntaxhighlight>

	You should now notice that the default values are set to "I love" and "Pizza". And we're done!		You should now notice that the default values are set to "I love" and "Pizza". And we're done!
Line 274:		Line 274:

	}		}
	</~~code~~>		</syntaxhighlight>

	=== More advanced ===		=== More advanced ===
Line 333:		Line 333:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

	=== Using the form ===		=== Using the form ===
Line 394:		Line 394:
	$form->display();		$form->display();
	echo $OUTPUT->footer();		echo $OUTPUT->footer();
	</~~code~~>		</syntaxhighlight>

	== See also ==		== See also ==

Poltawski at 14:25, 9 April 2017

2017-04-09T14:25:59Z

← Older revision		Revision as of 14:25, 9 April 2017
Line 395:		Line 395:
	echo $OUTPUT->footer();		echo $OUTPUT->footer();
	</code>		</code>

			== See also ==

			* [[Persistent]]
			* [[Exporter]]

Damyon: /* Grouping fields */

2016-12-20T05:33:42Z

Grouping fields

← Older revision		Revision as of 05:33, 20 December 2016
Line 219:		Line 219:
	Now it works because we've converted our group to individual properties. Note that you must call the parent method because we're automatically doing the same thing for you when you're using a text editor field.		Now it works because we've converted our group to individual properties. Note that you must call the parent method because we're automatically doing the same thing for you when you're using a text editor field.

	While this works fine, this is not enough as when we load an existing ~~objet~~ we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent.		While this works fine, this is not enough as when we load an existing object we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent.

	<code php>		<code php>

Fmcorz: Adding 'grouping fields'

2016-12-20T05:09:25Z

Adding 'grouping fields'

← Older revision		Revision as of 05:09, 20 December 2016
Line 145:		Line 145:

	This method is particularily useful when dealing with file managers.		This method is particularily useful when dealing with file managers.

			== Grouping fields ==

			There is a little bit of work to do when you want to group some properties together. Let's imagine that we are asking our users to pick amongst a few verbs and food. They can only tell us if they like or dislike something and what it is. Our form should display both the verb and the food next to each other, and to do so we need to use a group.

			First, let's update our persistent with the new two values we will store:

			<code php>
			protected static function define_properties() {
			...

			'verb' => array(
			'type' => PARAM_ALPHANUM,
			'default' => 'love'
			),
			'food' => array(
			'type' => PARAM_ALPHANUM,
			'default' => 'pizza'
			)

			...
			}
			</code>

			Secondly, we must add the group to the form:

			<code php>
			public function definition() {
			...

			// Food I like.
			$elements = [];
			$elements[] = $mform->createElement('select', 'verb', 'verb', [
			'hate' => 'I hate',
			'dislike' => 'I dislike',
			'like' => 'I like',
			'love' => 'I love'
			]);
			$elements[] = $mform->createElement('select', 'food', 'Food', [
			'egg' => 'Egg',
			'tofu' => 'Tofu',
			'chicken' => 'Chicken',
			'fish' => 'Fish',
			'pizza' => 'Pizza'
			]);
			$mform->addElement('group', 'foodilike', 'Food I like', $elements);

			...
			}
			</code>

			If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''.

			<code php>
			/**
			* Convert fields.
			*
			* @param stdClass $data The data.
			* @return stdClass
			*/
			protected static function convert_fields(stdClass $data) {
			$data = parent::convert_fields($data);

			// Convert the group to single properties.
			$data->verb = $data->foodilike['verb'];
			$data->food = $data->foodilike['food'];
			unset($data->foodilike);

			return $data;
			}
			</code>

			Now it works because we've converted our group to individual properties. Note that you must call the parent method because we're automatically doing the same thing for you when you're using a text editor field.

			While this works fine, this is not enough as when we load an existing objet we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent.

			<code php>
			/**
			* Get the default data.
			*
			* @return stdClass
			*/
			protected function get_default_data() {
			$data = parent::get_default_data();

			// Convert the single properties into a group.
			$data->foodilike = [
			'verb' => $data->verb,
			'food' => $data->food,
			];
			unset($data->verb);
			unset($data->food);

			return $data;
			}
			</code>

			You should now notice that the default values are set to "I love" and "Pizza". And we're done!

	== Examples ==		== Examples ==

Fmcorz: /* Defining the form fields */

2016-12-20T03:31:25Z

Defining the form fields

← Older revision		Revision as of 03:31, 20 December 2016
Line 39:		Line 39:
	All of this is pretty standard, except for the ''userid''. When creating a new 'status', we do not want our users to be in control of this value. Therefore we define it as a hidden value which we lock (using ''setConstant'') to the value we created our form with. All the mandatory fields (without a default value) of the persistent need to be added to the form. If your users cannot change their values, then they must be hidden and locked with ''setConstant''.		All of this is pretty standard, except for the ''userid''. When creating a new 'status', we do not want our users to be in control of this value. Therefore we define it as a hidden value which we lock (using ''setConstant'') to the value we created our form with. All the mandatory fields (without a default value) of the persistent need to be added to the form. If your users cannot change their values, then they must be hidden and locked with ''setConstant''.

	Did you notice that there isn't any call ~~the~~ ''setType'' in the above example? That is because we automatically do it for you based on the field name and your persistent's properties.		Did you notice that there isn't any call to ''setType'' in the above example? That is because we automatically do it for you based on the field name and your persistent's properties.

	Also note that the ''id'' property is not included. It is not required, nor recommended, to add it to your fields as it will be handled automatically.		Also note that the ''id'' property is not included. It is not required, nor recommended, to add it to your fields as it will be handled automatically.

Fmcorz: /* Defining the form fields */

2016-12-20T03:31:05Z

Defining the form fields

← Older revision		Revision as of 03:31, 20 December 2016
Line 38:		Line 38:

	All of this is pretty standard, except for the ''userid''. When creating a new 'status', we do not want our users to be in control of this value. Therefore we define it as a hidden value which we lock (using ''setConstant'') to the value we created our form with. All the mandatory fields (without a default value) of the persistent need to be added to the form. If your users cannot change their values, then they must be hidden and locked with ''setConstant''.		All of this is pretty standard, except for the ''userid''. When creating a new 'status', we do not want our users to be in control of this value. Therefore we define it as a hidden value which we lock (using ''setConstant'') to the value we created our form with. All the mandatory fields (without a default value) of the persistent need to be added to the form. If your users cannot change their values, then they must be hidden and locked with ''setConstant''.

			Did you notice that there isn't any call the ''setType'' in the above example? That is because we automatically do it for you based on the field name and your persistent's properties.

	Also note that the ''id'' property is not included. It is not required, nor recommended, to add it to your fields as it will be handled automatically.		Also note that the ''id'' property is not included. It is not required, nor recommended, to add it to your fields as it will be handled automatically.

Fmcorz: Remote setType

2016-12-20T03:27:47Z

Remote setType

← Older revision		Revision as of 03:27, 20 December 2016
Line 25:		Line 25:
	// User ID.		// User ID.
	$mform->addElement('hidden', 'userid');		$mform->addElement('hidden', 'userid');
	~~$mform->setType('userid', PARAM_INT);~~
	$mform->setConstant('userid', $this->_customdata['userid']);		$mform->setConstant('userid', $this->_customdata['userid']);

	// Message.		// Message.
	$mform->addElement('editor', 'message', 'Message');		$mform->addElement('editor', 'message', 'Message');
	~~$mform->setType('message', PARAM_RAW);~~

	// Location.		// Location.
	$mform->addElement('text', 'location', 'Location');		$mform->addElement('text', 'location', 'Location');
	~~$mform->setType('location', PARAM_ALPHANUMEXT);~~

	$this->add_action_buttons();		$this->add_action_buttons();
Line 165:		Line 162:
	// User ID.		// User ID.
	$mform->addElement('hidden', 'userid');		$mform->addElement('hidden', 'userid');
	~~$mform->setType('userid', PARAM_INT);~~
	$mform->setConstant('userid', $this->_customdata['userid']);		$mform->setConstant('userid', $this->_customdata['userid']);

	// Message.		// Message.
	$mform->addElement('editor', 'message', 'Message');		$mform->addElement('editor', 'message', 'Message');
	~~$mform->setType('message', PARAM_RAW);~~

	// Location.		// Location.
	$mform->addElement('text', 'location', 'Location');		$mform->addElement('text', 'location', 'Location');
	~~$mform->setType('location', PARAM_ALPHANUMEXT);~~

	$this->add_action_buttons();		$this->add_action_buttons();
Line 204:		Line 198:
	// User ID.		// User ID.
	$mform->addElement('hidden', 'userid');		$mform->addElement('hidden', 'userid');
	~~$mform->setType('userid', PARAM_INT);~~
	$mform->setConstant('userid', $this->_customdata['userid']);		$mform->setConstant('userid', $this->_customdata['userid']);

	// Message.		// Message.
	$mform->addElement('editor', 'message', 'Message');		$mform->addElement('editor', 'message', 'Message');
	~~$mform->setType('message', PARAM_RAW);~~

	// Location.		// Location.
	$mform->addElement('text', 'location', 'Location');		$mform->addElement('text', 'location', 'Location');
	~~$mform->setType('location', PARAM_ALPHANUMEXT);~~

	// Status update delay.		// Status update delay.

Damyon: /* Using the form */

2016-12-20T02:06:45Z

Using the form

← Older revision		Revision as of 02:06, 20 December 2016
Line 261:		Line 261:
	// means that we are going to be updating an object rather than creating a new one.		// means that we are going to be updating an object rather than creating a new one.
	$persistent = null;		$persistent = null;
	if (!~~empty~~($id)) {		if (!e mpty($id)) {
	$persistent = new status($id);		$persistent = new status($id);
	}		}
Line 275:		Line 275:
	if (($data = $form->get_data())) {		if (($data = $form->get_data())) {

	if (empty($data->id)) {		try {
	// If we don't have an ID, we know that we must create a new record.		if (empty($data->id)) {
	// Call your API to create a new persistent from this data.		// If we don't have an ID, we know that we must create a new record.
	// Or, do the following if you don't want capability checks (discouraged).		// Call your API to create a new persistent from this data.
	$persistent = new status(0, $data);		// Or, do the following if you don't want capability checks (discouraged).
	$persistent->create();		$persistent = new status(0, $data);
	} else {		$persistent->create();
	// We had an ID, this means that we are going to update a record.		} else {
	// Call your API to update the persistent from the data.		// We had an ID, this means that we are going to update a record.
	// Or, do the following if you don't want capability checks (discouraged).		// Call your API to update the persistent from the data.
	$persistent->from_record($data);		// Or, do the following if you don't want capability checks (discouraged).
	$persistent->update();		$persistent->from_record($data);
			$persistent->update();
			}
			\core\notification::success(get_string('changessaved'));
			} catch (Exception $e) {
			\core\notification::error($e->getMessage());
	}		}

Damyon: /* Using the form */

2016-12-20T02:00:20Z

Using the form

← Older revision		Revision as of 02:00, 20 December 2016
Line 246:		Line 246:
	=== Using the form ===		=== Using the form ===

	Consider the following code to be a page ~~thye~~ users will access at '/example.php'.		Consider the following code to be a page the users will access at '/example.php'.

	<code php>		<code php>

← Older revision		Revision as of 13:38, 14 July 2021
Line 7:		Line 7:
	In order for the form class to know what persistent we'll be dealing with, we must declare the ''protected static $persistentclass'' variable. The latter contains the fully qualified name of the persistent class.		In order for the form class to know what persistent we'll be dealing with, we must declare the ''protected static $persistentclass'' variable. The latter contains the fully qualified name of the persistent class.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/** @var string Persistent class name. */		/** @var string Persistent class name. */
	protected static $persistentclass = 'example\\status';		protected static $persistentclass = 'example\\status';
Line 16:		Line 16:
	Unfortunately this is not automatically done for us, so let's add our fields to the ''definition()'' method like you would do for any form.		Unfortunately this is not automatically done for us, so let's add our fields to the ''definition()'' method like you would do for any form.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/**		/**
	* Define the form.		* Define the form.
Line 51:		Line 51:
	Secondly, the persistent instance must be provided to the form through the custom data. That persistent instance will be used to populate the form with initial data, typically when you are editing an object. When you don't have a persistent instance yet, probably because your user will be creating a new one, then simply pass null.		Secondly, the persistent instance must be provided to the form through the custom data. That persistent instance will be used to populate the form with initial data, typically when you are editing an object. When you don't have a persistent instance yet, probably because your user will be creating a new one, then simply pass null.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$customdata = [		$customdata = [
	'persistent' => $persistent, // An instance, or null.		'persistent' => $persistent, // An instance, or null.
Line 61:		Line 61:
	Just like any other form, we will be using ''get_data()'' to validate the form. The only difference is that to determine whether we are editing an object, or creating a new one, we will check if the ''id'' value was returned to us. The persistent form will return the ID value from the persistent we gave it. Then it's up to you to decide how to apply the data, most likely you will defer the logic to another part of your code, one that ensures that all capability checks are fulfilled.		Just like any other form, we will be using ''get_data()'' to validate the form. The only difference is that to determine whether we are editing an object, or creating a new one, we will check if the ''id'' value was returned to us. The persistent form will return the ID value from the persistent we gave it. Then it's up to you to decide how to apply the data, most likely you will defer the logic to another part of your code, one that ensures that all capability checks are fulfilled.

	<~~code~~ php>		<syntaxhighlight lang="php">
	// Get the data. This ensures that the form was validated.		// Get the data. This ensures that the form was validated.
	if (($data = $form->get_data())) {		if (($data = $form->get_data())) {
Line 88:		Line 88:
	There are times when the built-in validation of the persistent is not enough. Usually you would use the method ''validation()'', but as the form persistent class does some extra stuff to make it easier for you, you must use the ''extra_validation()'' method. The latter works almost just like the ''validation()'' one.		There are times when the built-in validation of the persistent is not enough. Usually you would use the method ''validation()'', but as the form persistent class does some extra stuff to make it easier for you, you must use the ''extra_validation()'' method. The latter works almost just like the ''validation()'' one.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/**		/**
	* Extra validation.		* Extra validation.
Line 118:		Line 118:
	The fields to remove are never validated and they are not returned when calling ''get_data()''. By default the submit button is added to this list so that when we call ''get_data()'' we only get the persistent-related fields. To remove more fields, re-declare the ''protected static $fieldstoremove'' class variable.		The fields to remove are never validated and they are not returned when calling ''get_data()''. By default the submit button is added to this list so that when we call ''get_data()'' we only get the persistent-related fields. To remove more fields, re-declare the ''protected static $fieldstoremove'' class variable.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/** @var array Fields to remove when getting the final data. */		/** @var array Fields to remove when getting the final data. */
	protected static $fieldstoremove = array('submitbutton', 'areyouhappy');		protected static $fieldstoremove = array('submitbutton', 'areyouhappy');
Line 129:		Line 129:
	What about when we have a ''legit'' field but it does not belong to the persistent? We still want to validate it ourselves, but we don't want it to be validated by the persistent as it will cause an error. In that case we define it in the ''protected static $foreignfields'' class variable.		What about when we have a ''legit'' field but it does not belong to the persistent? We still want to validate it ourselves, but we don't want it to be validated by the persistent as it will cause an error. In that case we define it in the ''protected static $foreignfields'' class variable.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/** @var array Fields to remove from the persistent validation. */		/** @var array Fields to remove from the persistent validation. */
	protected static $foreignfields = array('updatedelay');		protected static $foreignfields = array('updatedelay');
Line 136:		Line 136:
	Now the persistent will not validate this field, and we will get the ''updatedelay'' value when we call ''get_data()''. Just don't forget to remove it before you feed the data to your persistent.		Now the persistent will not validate this field, and we will get the ''updatedelay'' value when we call ''get_data()''. Just don't forget to remove it before you feed the data to your persistent.

	<~~code~~ php>		<syntaxhighlight lang="php">
	if (($data = $form->get_data())) {		if (($data = $form->get_data())) {
	$updatedelay = $data->updatedelay;		$updatedelay = $data->updatedelay;
Line 152:		Line 152:
	First, let's update our persistent with the new two values we will store:		First, let's update our persistent with the new two values we will store:

	<~~code~~ php>		<syntaxhighlight lang="php">
	protected static function define_properties() {		protected static function define_properties() {
	...		...
Line 171:		Line 171:
	Secondly, we must add the group to the form:		Secondly, we must add the group to the form:

	<~~code~~ php>		<syntaxhighlight lang="php">
	public function definition() {		public function definition() {
	...		...
Line 198:		Line 198:
	If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''.		If you were to try the code like this, you would get an error telling you that the persistent did not expect to receive the property ''foodilike''. That's normal because the group is being set to the persistent which does not know what to do with it. In order to counter this we will need to convert the group to individual properties by extending the method ''convert_fields(stdClass $data)''.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/**		/**
	* Convert fields.		* Convert fields.
Line 221:		Line 221:
	While this works fine, this is not enough as when we load an existing object we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent.		While this works fine, this is not enough as when we load an existing object we must perform the same thing the other way around. We must convert the fields from our persistent to what the group field is expecting. To do so we override the method ''get_default_value()''. We're also taking care of the text editor for you here so don't forget to call the parent.

	<~~code~~ php>		<syntaxhighlight lang="php">
	/**		/**
	* Get the default data.		* Get the default data.
Line 248:		Line 248:
	=== Minimalist ===		=== Minimalist ===

	<~~code~~ php>		<syntaxhighlight lang="php">
	class status_form extends \core\form\persistent {		class status_form extends \core\form\persistent {

Line 278:		Line 278:
	=== More advanced ===		=== More advanced ===

	<~~code~~ php>		<syntaxhighlight lang="php">
	class status_form extends \core\form\persistent {		class status_form extends \core\form\persistent {

Line 339:		Line 339:
	Consider the following code to be a page the users will access at '/example.php'.		Consider the following code to be a page the users will access at '/example.php'.

	<~~code~~ php>		<syntaxhighlight lang="php">
	require 'config.php';		require 'config.php';

Persistent form - Revision history

Mudrd8mz: Text replacement - "" to ""

Mudrd8mz: Text replacement - "" to ""

Poltawski at 14:25, 9 April 2017

Damyon: /* Grouping fields */

Fmcorz: Adding 'grouping fields'

Fmcorz: /* Defining the form fields */

Fmcorz: /* Defining the form fields */

Fmcorz: Remote setType

Damyon: /* Using the form */

Damyon: /* Using the form */

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

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