Developing a Basic Component

How to add a component to Joomla

File / Folder Structure:

create    breed.xml       this is an XML (manifest) file that tells Joomla! how to install our component.

create    site/breed.php    this is the site entry point to the Breeds component

create    site/index.html    prevents web server from listing directory content

create    admin/index.html     prevents web server from listing directory content

create    admin/breed.php   this is the administrator entry point to the Breeds component

create    languages/site/en-GB/en-GB.com_breed.ini

create    languages/administrator/en-GB/en-GB.com_breed.ini

create    languages/administrator/en-GB/en-GB.com_breed.sys.ini

Introduction

In this tutorial we are going to create a Dog Breed component for Joomla Frontend and backend. This part is the starting point for the extension, we are going to build. What this component will do is, it will enable the user to enter dog breed details with images and will be able to display it on frontend. There would also be a frontend portion of the component, where the list will be displayed and the users would be able to edit and make entries on the basis ofrights assigned to them through ACL.

Joomla component development normally starts from creating backend interface first, even it is not compulsory but I recommend it to do so. I developed a component for a client of mine who’s requirement was to only construct the frontend and not the backend. I made it but then problems started coming out because there were no options or documentation or configuration settings at backend and client was contacting me again and again to even make minor changes. So, creating a backend, even if frontend is doing your major job, is still a good idea and in our case, it is compulsory.

Creating the base folder

First of all. we will create a base component folder, called com_breed. It means that name of the compoennt would be “breed”, followed by a “com_” prefix and all should be in lowercase. This “com_breed” folder is going to hold all the files that are compulsory for our component. This component name will also be used in the url as the option variable. So, the component name is important as we will be using it in all of the future lessons. It should be short and unique.

Installing the component

Complete steps on how to install the zip package of this basic component.

File Details

administrator/sql/install.mysql.utf8.sql is the project sql file.

breed.xml file

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.0" method="upgrade">
    <name>com_breed</name>
    <creationDate>2016-04-11</creationDate>
    <copyright>2016 nohman</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <author>nohman</author>
    <authorEmail>nohmanhabib@gmail.com</authorEmail>
    <authorUrl>https://www.codingace.com</authorUrl>
    <version>Breed: 1.0.0</version>
    <description></description>
  
    <files folder="site">
        <filename>index.html</filename>
        <filename>breed.php</filename>
    </files>

 <languages folder="languages/site">
 <language tag="en-GB">en-GB/en-GB.com_breed.ini</language>
 </languages>
  
    <administration>
        
        <menu img="media/com_breed/images/s_com_breed.png" >breed</menu>
        
       <submenu>     
       <menu link="option=com_breed&amp;view=breeds" view="breeds" 
       img="media/com_breed/images/s_breeds.png" alt="Breed/Breeds">breed</menu>
       </submenu>
        
       <files folder="administrator">
            <filename>index.html</filename>
            <filename>breed.php</filename>
            <folder>sql</folder>
        </files>

 <languages folder="languages/administrator"> 
 <language tag="en-GB">en-GB/en-GB.com_breed.ini</language>
 <language tag="en-GB">en-GB/en-GB.com_breed.sys.ini</language>
 </languages>
      
    </administration>
    <config>
        <fields name="params">
            <fieldset name="component">
                <field name="save_history" default="0" />
            </fieldset>
        </fields>

    </config>
</extension>

Create the component installation XML file

The first file we are going to create in our component folder is the XML file, also called as installation manifest. It means that Joomla extension installer makes use of this file to install the component files. The name of this file is breed.xml, identical to the component name. The naming convention is so much important because the installer will search for the manifest file, identical to the extension name.

Fill in the breed.xml file

Now, we are going to fill this xml maifest with some information. As you can see in the given breed.xml file above, on line 1, there is the XML prologue and while creating any XML document, we use it as a standard. In our case, it has a UTF-8 encoding.

From line 2, there starts our extension markup. It opens with an extension tag and has compulsory attributes, i.e, the extension type (in our case it is component), the Joomla version on which the extension we are going to develop can run (ours require 3.5) and then a method attribute. After that furthur tags are self explanatory. On line 3, the “name”tag refers to the component name, “creationdate” refers to the date at which component is developed, then there is the copyright and licensing information. I will provide a detailed information on licencing at the end of this tutorial. After that on line 7,8,9 the tags belong to the author or developer. It contains his/her name, email and if possible, the site url. The url could be the url of site where the component is going to be host, if you are developing it for distribution or it could be your company site url or your personal portfolio url. Then comes the component version and url. Versioning is important because you might be adding more features to component in future and you must know which component version is running on my Joomla. Description could be of one oer two lines and should briefly explain what this component will enable you to do or which problem it will solve.

After the component description, next comes the site folder files. These are currently only two but the list will expand when we will move further in tutorial. The first file, index.html behaves like an entry point to component and breed.php is a dispatcher file. This is the file which would be accessed by Joomla when or component will be called through url. I am explaining it further in this step. Then there is language file declaration. Joomla has a multilingual approach and to support this, language packs are used, representing different languages. I am  just giving an introduction here, so please don’t get confused here, as your concepts will be cleared after complete walk through development process. In the administrator tag, all the admin related file details are given, including language file for backend and the php related file that would be in use.

site/breed.php

<?php defined('_JEXEC') or die; ?>

<h1>Breed Listing Component</h1>

Create the component dispatcher file

We have our manifest file ready but Joomla needs to call a php based file to actually call and run the component. The file which code is mentioned above is the main component file with the same name as the component. i.e, com_breed.php. Joomla will be able to load the component now, when we will call it through “option=com_breed” in the url.

Fill in the breed.php file

Each php file in joomla starts with a header block and then a specific one line code for security purpose. The header block contains information in a commented form comprising extension version, package name, developer email, copyright and licensing information. To be compatible with joomla source code, the licensing should be GPL version 2 or later.

After this, the important security code comes and that is, defined _JEXEC or die. This code ensures that only Joomla is accessing this file and there is no direct call to it. For example, if someone is calling this file through url in a browser, this line of code will not let php server to execute the code inside it. If this code is not there, users can get access to the information which they are not supposed to see. So, sensitive data could be exposed in this way. We can also provide a message in the die statement.

administrator/breed.php

<?php  defined('_JEXEC') or die; ?>

<h1>Breed Listing Admin</h1>

 breed.php is the file that is first accessed by the joomla library when it tries to run the component or in other words, this is the component backend file that is executed first, when the component is accessed through url. For demonstration purpose, I am just giving a sample message here, in the above file, to be displayed in the component backend.

index.html

<html><body></body></html>

This is a blank html file, meant to stop files listing in the directory, if that directory is directly accessed through the url.

languages/administrator/en-GB/en-GB.com_breed.sys.ini

COM_BREED="Breed"

Create the sys language file

In this step, we are creating a base system language file for our component. The default language code or base language code of joomla is en-GB and it corresponds to a same name directory residing in the languages folder, both on front and backend. Now we are going to create a system language file for our component, in the backend languages en-GB folder. named en-GB.com_breed.sys.ini. The difference between a normal component language file and component system language file is, the system file is meant to translate the strings related to Joomla system, including component menu strings, description at the manage extensions page and also creating frontend menu string codes, we tackle with while creating new menu item from backend, which I will discuss in furthur lessons.

Currently this ini file is holding a single key, called “COM_BREED” and its corresponding value, “Breed”. What it is doing is, it is translating the name of component.

Discover and registering the the extension in joomla.

Now that we have created our basic component, it is the time to install it to joomla. First create the zip file of the component folder. You might have an instance of Joomla already running on your local host or online web server. I am assuming here that you are running it locally, so you can open the backend of it, as, http://localhost/(your joomla folder name)/administrator. Here, login with your admin username and password. After signing in, go to Extensions –> Manage on the top menu. It will load up an extension installation interface and through here, you can install your extension either through uploading the file, or uploading the folder to web server and then installing through folder or directly installing it, if your extension file resides on a web server and is accessible through a url.

We are installing our extension through first, “Upload Package File” option. Click on Choose File button and choose your zip file. After that, click on the “Upload and Install” button to install the extension. You will get a message that your extension has been installed successfully.

Now Click on the Components menu and you will see the new component, “Breeds” there.

Click on it and you will see see the breeder component backend.

To view the component on frontend, use the following url,

http://localhost/(joomla folder)/index.php?option=com_breed . Our component is uniquely identified here by passing component name to option variable.

Next –> Adding a view to component frontend