ADD fields, field manipulators

README.md

@@ -17,7 +17,7 @@ developing our project. The first run with simply renaming entries from a
 copy of the component **com_banners** did not work as expected.
 So let us start at the very beginning:
 
-### Adding basic files for component (b1_basic_backend)
+## Adding basic files for component (b1_basic_backend)
 
 With the git branch **b1_basic_backend**
 Add the following basic six files:
@@ -124,7 +124,7 @@ the directory /admin/language/en-GB/ naming it
 
 ---
 
-### Creating and managing Joomla database (b2_database)
+## Creating and managing Joomla database (b2_database)
 
 With the new git branch **b2_database** we continue our workflow.
 
@@ -295,7 +295,7 @@ Methods in the table objects are:
 
 ---
 
-### Get a Form in Joomla component
+## Get a Form in Joomla component (b3_form)
 
 The **Form** class of Joomla is used to create complex forms with flexible
 layouts and dynamic properties. First, the form fields are defined in the
@@ -440,7 +440,7 @@ just a line before `<folder>services</folder>` :
 
 ---
 
-### Adding administrator's actions (Back-end) - Save and Cancel
+## Adding administrator's actions (Back-end) - Save and Cancel (b4_actions)
 In the form View, you can add action buttons like "Save" and "Cancel" to submit the form
 or cancel the editing respectively. These buttons are added to the toolbar.
 
@@ -526,3 +526,189 @@ So, you either have data from the database, which you can get with `getItem()`,
 data from the session, which you can get with `getUserSate()`.
 
 ---
+## Automatic handling of fields (b5_field_manipulation)
+Values of some fields in the form can be automatically handled. There is no need to fill in
+the values while creating or editing a record.
+
+For example, `alias` can be generated from the `title` (or here, from the component's name),
+dates can be set to the current date or to `null`, user id can be obtained from current
+logged in user. Further may you also need to check validity of some fields like "should not
+be empty", `alias` should be unique, etc.
+
+The data submitted by the form needs to be modified before saving. This can be done at
+various places:
+
+- in the **Model class** by oeverriding the `save()` method or `preparetable()` method.
+- in the **Table class** by overriding the `bind()`, `check()`, or `store()` methods.
+
+#### 1. Model file
+**admin/src/Model/PartModel.php
+```php
+public function save($data)
+{
+	/* Add code to modify data before saving */
+
+	return parent:save($data);
+}
+```
+It is better to perform automatic handling of fields in the Table class as the data can be
+saved not only from administration, but also from frontend, API or by any other means.
+
+##### Example generating Alias
+Alias is generated from the `component_name` (or any other field) using **OutputFilter** class
+method.
+```php
+if (empty($data['alias']))
+{
+ 	if (Factory::getConfig()->get('unicodeslugs') == 1) {
+		$data['alias'] = OutputFilter::stringURLUnicodeSlug($data['component_name']);
+	} else {
+		$data['alias'] = OutputFilter::stringURLSafe($data['component_name']);
+	}
+}
+```
+##### Ordering
+The ordering value is calculated by finding the maximum value in the column and then
+incrementing it.
+```php
+/* if it is 0 -> get the max + 1 value */
+if (!$data['ordering']) {
+	$db = Factory::getDbo();
+	$query = $db->getQuery(true)
+		->select('MAX(ordering)')
+		->from('#__depot');
+
+	$db->setQuery($query);
+	$max = $db->loadResult();
+
+	$data['ordering'] = $max + 1;
+}
+
+```
+#### 2. bind()
+The `bind()` splits the article text or description into intro text and full text based on read
+more tag in the content. This method also converts fields data from arrays to JSON for
+saving into the database.
+
+```php
+public function bind($array, $ignore = '')
+{
+	if (isset($array['attribs']) && \is_array($array['attribs'])) {
+		$registry = new Registry($array['attribs']);
+		$array['attribs'] = (string) $registry;
+	}
+
+	return parent::bind($array, $ignore);
+}
+
+```
+
+#### 3. check()
+The check() checks whether title of the article is not empty. This method also sets the alias,
+hits, publishing dates.
+```php
+public function check()
+{
+	try {
+		parent::check();
+	}
+	catch (\Exception $e) {
+		$this->setError($e->getMessage());
+
+		return false;
+	}
+
+	if (trim($this->title) == '') {
+		$this->setError('Title (title) is not set.');
+
+		return false;
+	}
+
+	if (trim($this->alias) == '') {
+		$this->alias = $this->title;
+	}
+
+	$this->alias = ApplicationHelper::stringURLSave($this->alias, $this->language);
+
+	// Ensure any new items have compulsory fields set
+	if (!$this->id) {
+		// Hits must be zero on a new item
+		$this-hits = 0;
+	}
+
+	// Set publish_up to null if not set
+	if (!$this->publish_up) {
+		$this->publish_up = null;
+	}
+
+	// Set publish_down to null if not set
+	if (!$this->publish_down) {
+		$this->publish_down = null;
+	}
+
+	// Check the publish down date is not earlier than publish up.
+	if (!is_null($this->publish_up) && 
+		!is_null($this->publish_down) &&
+		$this->publish_down < $this->publish_up) {
+		// swap the dates
+		$temp = $this->publish_up;
+		$this->publish_up = $this->publish_down;
+		$this->publish_down = $temp;
+	}
+	return true;
+}
+```
+
+#### 4. store()
+The `store()` sets created and modified dates, created by and modified by users, and also
+checks for unique alias.
+```php
+public function store($updateNulls = true)
+{
+	$app = Factory::getApplication();
+	$date = Factory::getDate()->toSql();
+	$user = Factory::getUser();
+
+	if (!this->created) {
+		$this->created = $date;
+	}
+
+	if (!this->created_by) {
+		$this->created_by = $user->get('id');
+	}
+
+	if ($this->id) {
+		// Existing item
+		$this->modified_by = $user->get('id');
+		$this->modified = $date;
+	} else {
+
+		// Set modified to created date if not set
+		if (!$this->modified)) {
+			$this->modified = $this->created;
+		}
+
+		// Set modified_by to created_by user if not set 
+		if (empty($this->modified_by)) {
+			$this->modified_by = $this->created_by;
+		}
+	}
+
+	// Verify that the alias is unique
+	$table = $app->bootComponent('com_depot')->getMVCFactory()
+		->createTable('Part','Administrator');
+	if ($table->load(['alias' => $this->alias]) &&
+		($table->id != $this->id || $this->id == 0)) {
+		$this->setError('Alias is not unique.');
+
+		if ($table->state == -2) {
+			$this->setError('Alias is not unique. The item is in trash.');
+		}
+		return false;
+	}
+
+	return parent::store($updateNulls);
+}
+```
+
+---