Developing a component frontend update function/Simple frontend data entry
From Joomla! Documentation
< J3.x:Developing a component frontend update function
16 Add data entry[edit]
16.1 Description[edit]
Up to this step the HelloWorld component only enables the administrator to add or change items in the database. This step adds functionality to also allow a user to change data.
Typically this is relevant when the data is related or owned by the user. Therefore an owner field is added to the table storing the greeting messages. The use case for this scenario is enabling users to update their own greetings.
16.2 The changes[edit]
16.2.1 Files:[edit]
- README.md
- helloworld.xml
- admin/sql/updates/mysql/*
have been updated to reflect new version info.
New messages have been added to the language files mainly because of the addition of the new 'uid' field to the database table.
- admin/models/fields/helloworld.php
- site/language/en-GB/en-GB.com_helloworld.ini
16.2.2 site/views/helloworld/tmpl/default.php[edit]
The user must have a way to enter data. The html way of doing so is to develop a form, so this view is extended with such. Also, an new field 'uid' is added to the view to reflect the user/owner identification.
The variable data in the form is largely derived from the object $this->item which holds the current database record. The primary key for that record is $this->item->id and usually is indicated by the variable $id.
After data entry the user hits the enter key or the submit button which results in posting the form data (including the entered user data) to the server. The form 'action' tag is set up to redisplay the present page after a submit, and therefore the view site/views/helloworld/view.html.php is called again and acts on the posted data.
The form data could also be submitted to the server with the 'get' in stead of the 'post' method, but that will result in displaying the transferred data in the URL bar of the browser. That can be handy in some cases, for instance when the user wishes to copy the URL for later use. The 'post' method sends the data invisible to the user which is often a more appropriate approach for private data.
And finally, the form contains an additional tag JHtml::_('form.token'). This tag is generated by Joomla as a kind of checksum with enables the application to detect possible hacking of the form. That is a risk related to sending data to the server. Previous steps of HelloWorld only displayed data without receiving anything so use of this token was not needed. See for instance Joomla Doc: How to add CSRF anti-spoofing to forms for more information.
16.2.3 site/views/helloworld/view.html.php[edit]
The code in this file transfers data from the server for display in the defined view of section 16.2.2 . The difference with the previous version of HelloWorld is that the display can now result from two cases.
In the first place the 'view' will be displayed when the user browses to this page for the first time. In that case the 'view' method has to retrieve the data from the database.
The second case for displaying the 'view' is when the user has posted and submitted the form data after entering some values. This is detected by the 'view' method by inspecting the 'post' property of the form which now contains the user data at hand. The database will be updated with the posted data.
Joomla keeps 'post' data in the JFactory::getApplication()->input->post object. The variable $postmsg will retrieve the value of the greeting entered by the user, or will be null when no data has been posted like on the initial display of this page. Similarly, $getid will get the value of the item record id after a 'get' data command when the user specified 'id' in the URL, for instance with url localhost/index.php?option=com_helloworld&id=3 to select item record 3.
When 'postmsg' holds a value after a post, the view first checks if the current record item was owned by the current user. If this is not the case then the record will not be updated. This can also occur if the user is not logged in.
If the record is owned by the user, then the view calls the 'model' object to update the record in the database with $model->updateThisItem($postmsg) . Finally, the view will show a message indicating whether the update succeeded.
The model object caches some relevant data, including the current record, in a central 'state' object so that not every class involved in accessing and displaying the database record item needs to keep track of that data. The view retrieves and stores that data from and to the cache with $state->get() and $state→set(). Also the view's own 'get()' method is a shortcut for retrieving data from the model's cache.
As the model might process information for several other classes than this view, data specifically for this view will have a name prefixed by a unique identifier $context . We need to take care that we use the same prefix in all relevant class files.
16.2.4 site/models/helloworld.php[edit]
The model class is extended with the method 'updateThisItem' to write the submitted user data to the database. Note that also the model class internally uses the 'State' cache object to store and retrieve common data.
As an example some 'intelligence' has been designed to select the record item to be presented. The model takes the following steps:
- If the item is specified by the in the url like with localhost/index.php?option=com_helloworld&id=3, then this 'id' is used as primary key.
- If the id is not specified in the url, and the user is logged in, then the model searches for the first record item owned by this user, if that exists
- In other cases, record item with 'id=1' is retrieved.
- The item will be 'null' if nothing is found.
16.2.5 site/views/helloworld/tmpl/default.xml[edit]
This file contains a definition for the administrator menu management. When creating a new menu entry, a list of options is shown for selecting a menu type. The list now will show an 'HelloWorld' option to create a menu item which opens the data entry form.
16.2.6 admin/models/fields/helloworld.php, admin/models/forms/filter_helloworlds.xml, admin/models/forms/helloworld.xml[edit]
These files have been updated to support the additional 'uid' field. Note that in admin/models/forms/helloworld.xml this field is defined as type 'user' so that in the 'HelloWorld' admin edit page it is shown as an item with a pop-up that presents all defined users.
In the 'HelloWorld' admin list page the 'uid' field in the filter menu is just shown as a number, as specified in admin/models/forms/filter_helloworlds.xml .
See Joomla Doc: Standard form field types for more information.
16.3 Source files for this step[edit]
16.4 Testing the features of this step[edit]
- Prepare users and permissions, and test like previous step. And ...
- Create one or more (test) users with permissions to edit HelloWorld greet messages.
- Check that these users can change items in the front-end when logged in. Check that Public users and not logged-in users can not change items.