In this article by Joseph L. LeBlanc, you will learn about the architecture, design, and requirements of a general Joomla! component. You will also see how the component gets executed and is registered with the database. At the end, you will learn to create toolbars.
administrator/components/com_reviews/admin.reviews.php:
The following folder diagram shows the Joomla! root with the administrator folder expanded:
Notice that the administrator folder has a structure similar to the root folder. It is important to differentiate between the two, else you may place your code in the wrong folder and it will fail to execute until youmove it.
We will perform this registration using the following query. It is assumed that your database prefix is jos_. If not, replace jos_ with the prefix you chose. If you prefer to work with direct SQL statements on a command-line interface, enter the following query in your console:
Adding this record gives the system some basic information about your component. It states the name you want to use for the component, which can contain spaces and punctuation. You can put in specific links to go to both the front end and back end. The image to be used on the Components menu can be specified. Also as thedescription in the browser status bar can be made available. It is not necessary to addthis query while developing the component; once you create the basic directories andfiles, your component is ready to be executed. However, it does add a menu itemin the back end and makes it possible to add an appropriate link in the front endwithout hard coding a URL.
After the record is successfully entered, go to any page in the back end and refresh it. When you move the mouse cursor over the Components menu you should see the new option:
Now that the component is registered, you can also create a link for the front end. Go to Menus | Main Menu and click New. From this screen, select Restaurant Reviews. Enter Reviews as the Name. The following screen will be observed:
Now click Save and go to the front end. You should now see Reviews listed as an option.
You could just break out your PHP skills and start coding the component, ensuring all front-end requests go through http://localhost/joomla/index.php?option=com_reviews and all back-end requests go though http://localhost/ joomla/administrator/index.php?option=com_reviews. Joomla! is flexible enough to let you do as you please. In some cases, you will have existing code that you may want to use and you will need to split it into appropriate files. But for the restaurant reviews, you will start a new Joomla! component from scratch. You have the opportunity to design everything with Joomla's toolbars, users, database classes, and libraries in mind. These elements will save you a lotof time once you understand how theywork.
To start, create the toolbar.reviews.html.php file in the administrator/components/com_reviews folder and enter in the following code:
tags along with your custom navigation.
The toolbars are now defined, but you need to add some code that will decide which one to display. In the back end, Joomla! automatically loads the file beginning with the component name and ending in .reviews.php in the upper right-hand portion of the screen. Add the following code into toolbar.reviews.php in the administrator/components/com_reviews folder:
To see the other toolbar, add &task=add to the end of the URL in your browser, then load it. The toolbar should appear like this:
Your users will certainly not want to add the task variable at the end of the URL as they navigate through your component. How will they be able to use the second toolbar then? Each button on the toolbar represents a different task. When one is clicked, the associated task is added to your form and it is automatically submitted. Once the appropriate form is in place, a click on the New button from the first screen will pull up the toolbar seen in the second. Since we do not yet have any forms in the back end, these toolbar buttons will not function. These will start working in the next chapter when we build out the rest of the back end.
Joomla!'s Component Structure
Joomla! employs a specific naming scheme, which is used by all components. Each component in the system has a unique name with no spaces. The code is split into two folders, each bearing the component name prefixed by com_. The component used here will be called reviews. Therefore, you will have to create two folders named com_reviews:- Create one in the folder named components for the front end.
- Create one in the folder named components within the administrator folder for the back end.
Executing the Component
All front-end requests in Joomla! go through index.php in the root directory. Different components can be loaded by setting the option variable in the URL GET string. If you install Joomla! on a local web server in a directory titled joomla, the URL for accessing the site will be http://localhost/joomla/index.php or something similar. Assuming this is the case, you can load the component's front end by opening http://localhost/joomla/index.php?option=com_reviews in your browser. At this point, the screen should be essentially blank, apart from the common template elements and modules. To make this component slightly more useful, open reviews.php and add the following code, then refresh the browser:defined( '_JEXEC' ) or die( 'Restricted access' ); echo 'Your screen will look similar to the following:Restaurant Reviews'; ?>
You may be wondering why we called defined() at the beginning of the file. This is a check to ensure that the code is called through Joomla! instead of being accessed directly at components/com_reviews/reviews.php. Joomla! automaticallyconfigures the environment with some security safeguards that can be defeated ifsomeone is able to directly execute the code for your component.
For the back end, drop this code into
administrator/components/com_reviews/admin.reviews.php:
defined( '_JEXEC' ) or die( 'Restricted access' ); echo 'Restaurant Reviews'; ?>Go to http://localhost/joomla/administrator/index.php?option=com_reviews and compare your result to this:
Joomla!'s Division between Front End and Back End
For all Joomla! components, code empowering the back-end portion is kept away from the front-end code. In some instances, such as the database table class, the back end will use certain files from the front end, but otherwise the two are separate. Security is enhanced as you are less likely to slip the administrative functions into the front-end code. This is an important distinction as the front end and back end are similar in structure.The following folder diagram shows the Joomla! root with the administrator folder expanded:
Registering Your Component in the Database
You now know how to access both the front end and back end of the component. Although you could keep typing in the URLs each time you wanted to execute a piece of code, this will not be acceptable to your users. Navigation can be provided if you register the component in the database by adding a row to the components table.We will perform this registration using the following query. It is assumed that your database prefix is jos_. If not, replace jos_ with the prefix you chose. If you prefer to work with direct SQL statements on a command-line interface, enter the following query in your console:
INSERT INTO jos_components (name, link, admin_menu_link,
admin_menu_alt, 'option', admin_menu_img, params)
VALUES ('Restaurant Reviews', 'option=com_reviews',
'option=com_reviews', 'Manage Reviews', 'com_reviews',
'js/ThemeOffice/component.png', '');If you prefer to use a GUI or web-based database manager such as phpMyAdmin, enter Restaurant Reviews for name, option=com_reviews for link and admin_menu_link, Manage Reviews for admin_menu_alt, com_reviews for option, and js/ThemeOffice/component.png for admin_menu_img. Leave all of the other fields blank. The fields menuid, parent, ordering, and iscore will default to 0, while enabled will default to 1.Adding this record gives the system some basic information about your component. It states the name you want to use for the component, which can contain spaces and punctuation. You can put in specific links to go to both the front end and back end. The image to be used on the Components menu can be specified. Also as thedescription in the browser status bar can be made available. It is not necessary to addthis query while developing the component; once you create the basic directories andfiles, your component is ready to be executed. However, it does add a menu itemin the back end and makes it possible to add an appropriate link in the front endwithout hard coding a URL.
After the record is successfully entered, go to any page in the back end and refresh it. When you move the mouse cursor over the Components menu you should see the new option:
Creating Toolbars
Throughout the back end, all the core components implement toolbars with similarbuttons for saving, deleting, editing, and publishing items. You can use these buttons in your component so that frequent administrators will have a seamless experience.To start, create the toolbar.reviews.html.php file in the administrator/components/com_reviews folder and enter in the following code:
defined( '_JEXEC' ) or die( 'Restricted access' );
class TOOLBAR_reviews {
function _NEW() {
JToolBarHelper::save();
JToolBarHelper::apply();
JToolBarHelper::cancel();
}
function _DEFAULT() {
JToolBarHelper::title( JText::_( 'Restaurant Reviews' ),
'generic.png' );
JToolBarHelper::publishList();
JToolBarHelper::unpublishList();
JToolBarHelper::editList();
JToolBarHelper::deleteList();
JToolBarHelper::addNew();
}
}
?>Files containing output codes are usually organized into classes, like the code here with TOOLBAR_reviews. Each member function here represents a different toolbar. The class JToolBarHelper contains functions that generate all the HTML necessary to build toolbars. When desired, you can also add custom HTML output from within these functions. Be aware that the toolbars lie within HTML tables; you will probably want to add tags along with your custom navigation.
The toolbars are now defined, but you need to add some code that will decide which one to display. In the back end, Joomla! automatically loads the file beginning with the component name and ending in .reviews.php in the upper right-hand portion of the screen. Add the following code into toolbar.reviews.php in the administrator/components/com_reviews folder:
defined( '_JEXEC' ) or die( 'Restricted access' );
require_once( JApplicationHelper::getPath( 'toolbar_html' ) );
switch($task)
{
case 'edit':
case 'add':
TOOLBAR_reviews::_NEW();
break;
default:
TOOLBAR_reviews::_DEFAULT();
break;
}
?>The line containing require_once(...) uses the getPath() member function of the JApplicationHelper class. The call to getPath() allows you to call up the toolbar.reviews.html.php file without committing to a component name. Later, even if you change the name to 'Restaurants' and also change the filenames, this line of code will still load the output code for the toolbar with no modification.You may be wondering why we are creating two files to begin with, toolbar.reviews.php and toolbar.reviews.html.php. The preferred coding style among component developers is to keep the processing logic in a file completely separate from where the actual output takes place. This makes it easier to add features later and to potentially share the code with others.
After toolbar.reviews.php loads the file with the output class, you need to decide which toolbar should be displayed. The request variable $task is automatically registered in global scope by Joomla! and is used to direct the logic flow within the component. With your toolbar code in place, refresh the browser in the back end and go to Restaurant Reviews under Components and you should see thefollowing screen:Available Toolbar Buttons
Joomla! allows you to override any button with your own task and label, passing them as the first and second parameters respectively. The following buttons areavailable with the standard distribution of Joomla!:If you would like to create a custom button that looks and behaves like the core ones, use the custom() member function of JToolBarHelper, passing in the task, icon, mouse-over image, and text description as the respective parameters.
