J3.x

Developing a component frontend update function/Record item editing page

From Joomla! Documentation

< J3.x:Developing a component frontend update function
Revision as of 10:56, 24 October 2022 by Cmb (talk | contribs) (Changes for Word2Watch compliance. Capitalization and markup changes.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Joomla! 
3.x
Tutorial
Developing a component frontend update function


17 Frontend Data Entry as in the Backend[edit]

17.1 Description[edit]

As noted earlier, the Administrator (Backend) of Joomla shows that it features by default already quite some functionality for access to data in the database. This includes standard list and edit views for selecting, publishing, adding, deleting and updating records, including toolbars and options for searching, filtering, ordering and pagination.

The previous step in this tutorial showed how to build a view for the user to update database items more or less from scratch. It would be nice of course if we could just use all the standard Joomla Backend features in the Frontend as well for our own components for end users. Reusing existing functionality generally is better than reinventing the wheel.

This step shows how to 'clone' a Backend item editing page for use in the Frontend by end users.

17.1.1 Standard Architecture[edit]

For the Backend Joomla uses a standard architecture for list views and editing pages. As a result admin pages for all components look similar. Pages to a large extend are defined by means of xml files and this reduces the need for coding to a minimum. The architecture however still offers a lot of options and interfaces to adapt the pages to specific needs.

This is a powerful proposition, but of course requires a solid understanding of all those options. That will take some time but pays back due to better development results. As this architecture is used for the Backend, a good level of understanding is required anyway.

17.1.2 Clone the Backend to the Frontend[edit]

Joomla adheres to the MVC (model-view-controller) architecture, so the functionality of a feature is implemented in the models, views and controllers directories of the admin and site trees, respectively. As we intend to clone the Backend functions to the Frontend we start by copying the admin/models, admin/views and admin/controllers directory tree to their site/* counterparts.

As this step of the tutorial is concerned only with the edit page and not yet with the list view, we only copy the 'helloworld' (singular) files and not the 'helloworlds' (plural) ones. Adding the latter will be addressed in a next tutorial step.

Some modifications are still needed, and the differences between the Backend files and their Frontend counterparts are covered in the next sections.

17.2 The Changes[edit]

17.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.

  • admin/language/en-GB/en-GB.com_helloworld.ini
  • site/language/en-GB/en-GB.com_helloworld.ini

The Backend has not been changed for this step.

17.2.2 site/views/helloworld/tmpl/edit.php[edit]

The Joomla architecture expects edit tasks by default to be performed by a layout template called edit, so our layout file is site/views/helloworld/tmpl/edit.php instead of .../tmpl/default.php. This PHP file is generic in that it does not contain references to particular texts, labels or fields, but it calls the MVC model to provide the definitions for these. The layout code then generates a page for display according to these definitions.

This edit.php file therefore can be used without modification for both Backend and Frontend, and even in other components.

Note that the architecture for these pages originates from usage in the Backend, and in some places this is explicitly visible in the code. For instance, the architecture expects the form name and id to be adminForm even when we use the layout template in the Frontend.

17.2.3 site/views/helloworld/tmpl/edit.xml[edit]

This file contains a definition for the administrator menu management, as in the .../tmpl/default.xml file of step 16.2.5. This feature has no counterpart for the Backend HelloWorld pages, so there is no admin/views/helloworld/tmpl/edit.xml.

17.2.4 site/views/helloworld/view.html.php and views/helloworld/submitbutton.js[edit]

For the larger part the Backend code can be reused. Changes are:

  • Usually the edit page is accessed by first selecting a record item from the overview list page. This step of the tutorial only implements the edit page and lacks the list page. The display function therefore starts with retrieving the item id from the URL as in localhost/index.php?option=com_helloworld&id=3. The id parameter is stored in the State cache so that the model functions can access it.
  • setLayout('edit') specifies that the tmpl/edit.php layout template should be called to display the page, in stead of the tmpl/default.php template.
  • Next, the function includeAdminEnv() is called. This function takes care that the required Backend functions are also available to the present view class that runs in the Frontend. By default, the admin language files and helper functions such as JtoolBarHelper etc. are only available from the Backend code.
  • Joomla support Access Permissions to make sure that data is only available for users with the proper access rights. Permissions can be set at global Joomla level, at component level but also at record level. The latter is arranged by the asset_id field of the data records.For demonstration purposes the record level access is relaxed a little: normally a user can not access a record if its permission has not been setup properly and asset_id has been filled accordingly. We allow users to retrieve an uninitialized record item, and the asset_id field will be properly set on the fly if the record is modified and rewritten to the database. This procedure makes it easier to import new records.
  • For demonstration purposes the edit page now also displays the current user id, and the record item id, although these parameters in general are only used internally.The code for this actually belongs in the tmpl/edit.php but as it is only for demonstration the code is compiled in the view in order to keep the standard edit.php unchanged.
  • The setDocument() function is updated to refer to the Frontend settings instead of the Backend.
  • Some CSS styles for the toolbar are by default available in the Backend but not in the Frontend. These styles have been cloned to media/css/helloworld.css to support the Frontend toolbar.
  • The Backend JavaScript code views/helloworld/submitbutton.js that is called by the Submit buttons can be reused without modifications.

Although the above seems quite a story, the changes are all quite small and to a great extent the Backend edit page works in the Frontend as well, including the toolbar. The page display format now follows the Frontend style, so may use different fonts, sizes and colors etc, but the functionality and general layout is equal for Back and Frontend.

17.2.5 site/models/forms/helloworld.xml[edit]

The edit page definition file site/models/forms/helloworld.xml is just a clone of the Backend file. Note that the edit page displays both the record item fields, but also includes a section to edit global HelloWorld component parameters and a section with permission specifications. This shows that a straightforward clone of Backend features is possible, although in a real life application the latter two sections are presumably removed from the Frontend edit page.

This is a matter of adapting this helloworld.xml file, and will be discussed in a next step of this tutorial.

Although not strictly required, helloworld.xml is changed in one place: the user id field 'uid'. In the Backend this field shows a popup window with an extensive overview of all user accounts; probably too extensive for normal use in the Frontend. So the field is replaced by a dropdown list showing only the user names without additional options. The dropdown is based on a straightforward SQL query on the #__users table to generate the list. You can try out the difference by just using a copy of admin/models/forms/helloworld.xml in stead of this modified version.

See Joomla Doc: Standard form field types for more information.

17.2.6 site/models/helloworld.php and site/models/forms/helloworld.js[edit]

As both data and views are (almost) the same in both Frontend and Backend, also the model is (almost) equal. Only the reference to the javascript file site/models/forms/helloworld.js is adapted to the Frontend. The JavaScript file itself is an unchanged copy. Its purpose is validation of the syntax of the greeting entered by the user.

17.2.7 site/controllers/helloworld.php[edit]

That leaves us with the controller. This class is based on JControllerForm, and the HelloWorld super class needs almost no additional functionality, neither for the Backend or the Frontend. The view changes follow:

  • JControllerForm expects a combination of a list view page for selecting a record item, and an edit page for changing the item. For this tutorial step we have no list view page, so we indicate in the constructor to immediately open the edit page view 'helloworld' in stead of the list page (which would have been 'helloworlds' as expected by JcontrollerForm by default).
  • In allowEdit() we add a relaxed permission check for when asset_id is still uninitialized. See 17.2.4.
  • an override of the function allowAdd() is not required for this tutorial. Not in the Backend either, for that matter.

17.2.8 site/controller.php, site/helloworld.php[edit]

The Backend base controller include some additional calls in view of the layout of the admin pages which are not required in the Frontend.

The Backend controller also checks whether the user has sufficient administrative access rights. Permissions are a topic of its own, and is addressed in the separate next step 19.

17.3 Source Files for This Step[edit]

17.4 Testing the Features of This Step[edit]

  • Prepare users and permissions, and test as in previous step. And...
  • Test that everybody can open the edit page with e.g. localhost/index.php?option=com_helloworld&id=3.
  • Check that only logged-in users have 'edit' etc buttons on their toolbar.
  • Check that only logged-in users (with proper permissions) can update the page.
  • View some other message items with other id's. Create and delete some items.
  • Verify that this Frontend page has the same functionality as the Backend page apart from some minor differences.