Step 1 - The Basics

Thank you for your contribution: 

You can already sponsor this chapter!

Ornate StaircaseLet's collect a few facts about the first step to our Real Estate component. A component has to have a unique name and the easiest way to achieve that is to use your name or your company's name in the beginning.

  • The human readable name for the component is "Cocoate Real Estate".
  • The machine readable name for the component is cocoaterealestate (While writing this component example I learned that it is better to avoid underscores in file names).
  • The folders the component lives in are called com_cocoaterealestate
  • It has one view called object. This view should display later on listings of houses.
  • We need the possibility of creating a menu item to access the component
  • We want to have a menu item in the backend that displays coming soon.

Frontend and Backend

In "extension speech" the frontend is called site and the backend is called admin

If you have a menu item on your page that leads to your component and a user clicks on this link,

  • Joomla! evaluates the URL path: /index.php?option=com_cocoaterealestate
  • It searches the database components table for a component called cocoaterealestate.
  • It looks for a folder called com_cocoaterealestate in the site folder components.
  • In this folder it looks for a file called cocoaterealestate.php.
  • It interprets this file.

The same happens in the admin area. If a manager or an administrator clicks the menu item,

  • Joomla! evaluates the URL path: /administrator/index.php?option=com_cocoaterealestate
  • It searches the database components table for a component called cocoaterealestate.
  • It looks for a folder called com_cocoaterealestate in the admin folder administrator/components ..
  • In this folder it looks for a file called cocoaterealestate.php.
  • It interprets this file.

Because we have to build two applications in one component with the same name, we have to have a structure. To interpret in the right way, you need several files.

  • cocoaterealestate.xml – The XML file with all the information for the installer
  • cocoaterealestate.php – The starting point of your component
  • controller.php – The C in MVC, the controller
  • views/object/view.html.php – The file which gets the data from the model (the M in MVC) and prepares it for the view (the V in MVC)
  • views/object/tmpl/default.php – A default template for the component area of the page. It is possible to override this default template with the installed Joomla! template.

We need the same structure in the admin interface. Both applications are totally separate.

Files and Installation

Each extension needs a record in the extension table of the database. Without this record it doesn't exist in the "eyes" of the Joomla! CMS and it is not possible to use the extension, even when all files are in the right place. The database record will usually be created when you install the component.

But how to start? You have to write the component first :)

As always you have two possibilities.

Discover Extension

Since Joomla! 1.6 there is a discover option in the Extension Manager. You can place the files of your component in the right folders and click the discover option in the extension manager. It will read the components .xml file and update the extension table. The component is ready to use.

Your files should be placed like this. A file index.html has to be placed in each folder for security reasons.

/component/com_cocoaterealestate/cocoaterealestate.php

/component/com_cocoaterealestate/controller.php

/component/com_cocoaterealestate/index.html

/component/com_cocoaterealestate/view/object/view.html.php

/component/com_cocoaterealestate/view/object/index.html

/component/com_cocoaterealestate/view/object/tmpl/default.php

/component/com_cocoaterealestate/view/object/tmpl/default.xml

/component/com_cocoaterealestate/view/object/tmpl/index.html

/component/com_cocoaterealestate/view/index.html

/administrator/components/com_cocoaterealestate/cocoaterealestate.php

/administrator/components/com_cocoaterealestate/cocoaterealestate.xml

/administrator/components/com_cocoaterealestate/index.html

Install Extension

The other way is to install your extension via the Joomla! Extension Manager. In this case you have to place the files outside of Joomla!, compress them to a zip archive and upload it to the installer. After installation, the component is ready to use.

Your files should be placed like this. A file index.html has to be placed in each folder for security reasons.

/site/cocoaterealestate.php

/site/controller.php

/site/index.html

/site/view/object/view.html.php

/site/view/object/index.html

/site/view/object/tmpl/default.php

/site/view/object/tmpl/default.xml

/site/view/object/tmpl/index.html

/site/view/index.html

/administrator/cocoaterealestate.php

/administrator/cocoaterealestate.xml

/administrator/index.html

At the end of this chapter you find the attached example component.

The Code

In total we need 7 files with code and the index.html file.

File: index.html

If a visitor navigates his browser directly to a folder of the component, it would be possible, depending on the configuration of the webserver, that he would see a directory of that folder. To avoid that you have to place a file called index.html in each folder (Listing 1). This requirement is a moot point (The files of wrath) but it is still necessary to get listed in the Joomla! Extension Directory.

<!DOCTYPE html><title></title>

Listing 1: index.html

File: /administrator/cocoaterealestate.php

This is the file, which is executed when you click the component in the administration area (Figure 1). It can contain "everything" :)

cocoate.com/node/10196Step1-Coming Soon

Figure 1: Output in Backend

Coming soon!

Listing 2: /administrator/cocoaterealestate.php

File: /administrator/cocoaterealestate.xml

The .xml file contains meta data and the information where to put the files. You can see parts of the data in Figure 2.

cocoate.com/node/10196Step1-Extension Manager

Figure 2: XML Data in Extension Manager

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.7.0" method="upgrade">

    <name>Cocoate Real Estate</name>
    <!-- The following elements are optional and free of formatting constraints -->
    <creationDate>November 2011</creationDate>
    <author>Hagen Graf</author>
    <authorEmail>hagen@cocoate.com</authorEmail>
    <authorUrl>http://cocoate.com</authorUrl>
    <copyright>2006-2011 cocoate.com - All rights reserved</copyright>
    <license>GPL 2</license>
    <!--  The version string is stored in the components table -->
    <version>0.0.1</version>
    <!-- The description is optional and defaults to the name -->
    <description>House listings on your website.</description>

    <!-- Note the folder attribute: This attribute describes the folder
        to copy FROM in the package to install therefore files copied
        in this section are copied from "site/" in the package -->
    <files folder="site">
        <filename>index.html</filename>
        <filename>cocoaterealestate.php</filename>
        <filename>controller.php</filename>
        <folder>views</folder>
    </files>

    <administration>
        <menu>Cocoate Real Estate</menu>
        <!-- Note the folder attribute: This attribute describes the folder
            to copy FROM in the package to install therefore files copied
            in this section are copied from "admin/" in the package -->
        <files folder="admin">
            <filename>index.html</filename>
            <filename>cocoaterealestate.php</filename>
        </files>
    </administration>
</extension>

Listing 3: /administrator/cocoaterealestate.xml

File: /site/cocoaterealestate.php

The defined('_JEXEC') or die; statement has to be for security reasons at the top of each .php file. This statement checks to see if the file is being called from within a Joomla! session (Listing 4).

// No direct access to this file
defined('_JEXEC') or die;

// Import of the necessary classes
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by CocoateRealEstate
$controller = JController::getInstance('CocoateRealEstate');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();

Listing 4: /site/cocoaterealestate.php

File: /site/controller.php

This is the controller, the C from MVC. At the moment there is nothing to control, so the file remains empty (Listing 5)

defined('_JEXEC') or die;
jimport('joomla.application.component.controller');
class CocoateRealEstateController extends JController
{
}

Listing 5: /site/controller.php

File: /site/view/object/view.html.php

Views are the V in MVC and they are separated in various views. The name of the folder is the name of the view. In our case we'll need a listing of all houses and a detailed page for one object. The views are separated in files for collecting the necessary data from the model (which will come later too) and the template file with the markup. In Listing 6 you see the data collection for the objects list.

// No direct access to this file
defined('_JEXEC') or die;
jimport('joomla.application.component.view');
class CocoateRealEstateViewObject extends JView
{
    function display($tpl = null)
    {
        // Assign data to the view
        $this->item = 'Cocoate Real Estate';

        // Display the view
        parent::display($tpl);
    }
}

Listing 6: /site/view/object/view.html.php

File: /site/view/object/tmpl/default.php

This is the template file with the markup (Listing 7). This file can be copied to and overwritten by the main Joomla! template.

// No direct access to this file
defined('_JEXEC') or die;
?>
<h1><?php echo $this->item; ?></h1>

Listing 7: /site/view/object/tmpl/default.php

File: /site/view/object/tmpl/default.xml

This is the configuration file for the menu item Manager (Figure 3, Listing 8)

cocoate.com/node/10196Step1-Menu Item

Figure 3: XML Data in Menu Manager

<?xml version="1.0" encoding="utf-8"?>
<metadata>
    <layout title="Cocoate Real Estate">
        <message>Object</message>
    </layout>
</metadata>

Listing 8: /site/view/object/tmpl/default.xml

AttachmentSize
com_coco_real_estate-0.0.1.zip18.59 KB

Comments

This is great stuff. I am surprised that there aren't more contributions or comments because what you are doing by explaining the basic principals and thinking behind the joomla infrastructure is really helpful.
Thanks for this, and when I get to be good enough at it I'll hope to contribute some content.

Richard

Hi

Sorry but..
It don't work

I've downloaded the zip and then tried to install via the Extension manager and nothing
I've created the directory and the tried with the Discover Extension and nothing
I see in the zip there isn't the xml so I saved it into the zip and retried the above but the same

I'm really new to joomla, please can you help me?

Thanks

P.S. I'm on a 1.7.30 version on windows via XAMPP and the standard joomla installation works fine... I think

Please try again, seems there was a problem with the file
Hagen

Great!

Now it installs!

Don't create menu item but install.

Thanks

Hi grat tutorial.

But i have a question. How can we accesing file from a joomla component from other files located on diferent server?

To explain better :

I understand that from the joomla we use the link /administrator/index.php?option=com_cocoaterealestate to acces the component, but how can we acces the same component from other servers.

For example I have an oauth client wich call a file request-token.php located on a joomla component
$info = getRequestToken("http://domain.com/joomla/administrator/c...");

Where do I must to put the request_token.php file in the joomla component so the file to use the joomla framework ( e.g. $db = JFactory::getDBO(); ..etc) and how can access this file from the client application?

Hi,

In this part, how we know that the view name to be displayed is "Object"? This name does not appear anywhere!

his my my idea, see above
"It has one view called object. This view should display later on listings of houses."
A house = an object
Hagen

If you follow the structure the ebook suggest, the zip wont install.
But if you download "com_coco_real_estate-0.0.1.zip", attached in this page, it will install nicely.
Why is it ?