J3.x

Developing a component frontend update function/Record item editing page

From Joomla! Documentation

< J3.x:Developing a component frontend update function
Joomla! 
3.x
Tutorial
Developing a component frontend update function


17 Frontend data entry like in the backend

17.1 Description

As noted earlier, the administrative 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

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 easily pays back because of 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

Joomla adheres to the MVC (model-view-controller) architecture, so the functionality of a feature like the edit page 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

17.2.1 Files:

  • 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 administrative backend has not been changed for this step.

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

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 in stead 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 back- and front-end, and even in other components as well.

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

This file contains a definition for the administrator menu management, just like the .../tmpl/default.xml in the previous 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, views/helloworld/submitbutton.js

For the larger part the admin 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 like 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 like 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 in stead of the backend.
  • Some css styles for the toolbar are by default available in the backend but lack 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 front-end.

17.2.5 site/models/forms/helloworld.xml

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 admin 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, site/models/forms/helloworld.js

As both data and views are (almost) the same in both front- 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

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 exptected 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

The back-end base controller include some additional calls in view of the layout of the admin pages which are not required in the front-end.

The back-end 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

17.4 Testing the features of this step

  • Prepare users and permissions, and test like 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 'front-end' page has the same functionality as the back-end page. Apart from some minor differences.