Actions

User

Difference between revisions of "Rvsjoen/tutorial/Developing an MVC Component/Part 01"

From Joomla! Documentation

< User:Rvsjoen‎ | tutorial/Developing an MVC Component
(Installing your extension)
m (Installation manifest)
 
(43 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= Developing a Basic Component =
 
= Developing a Basic Component =
Let's create a ''Hello World!'' component.
+
Let's create a ''Hello World!'' component. All file name and path references in this tutorial are relative to the directory you are developing your extension in.
  
=== Public display ===
+
When you follow this tutorial and create files and directories you will notice that we are referring to a '''site''' folder and an '''admin''' folder. These are folders inside the component package (not in the Joomla! tree). And during installation the contents of '''site''' will be copied to the Joomla! <tt>components/com_helloworld</tt> folder and the contents of the '''admin''' folder will be copied to the Joomla! <tt>administrator/components/com_helloworld</tt> folder. If you wish to develop your extension directly in the Joomla! tree, then you may skip the '''site''' and '''admin''' folder and place the files directly in the correct folders inside the Joomla! tree. Note that if you do take this approach, you are going to have to install the component the first time using the discovery feature explained later in this part of the tutorial.
With your favorite file manager and editor, create a file ''yoursite/components/com_helloworld/helloworld.php'' containing
+
 
 +
=== Basic frontend ===
 +
When Joomla! looks for a component it will look at the '''option''' variable given in the url, in our case this will be '''option=com_helloworld'''. This means that Joomla! will look in the <tt>components</tt> directory for a folder named <tt>com_helloworld</tt> and load the file <tt>helloworld.php</tt> contained within that directory. So let us go ahead and create such an '''entry point'''.
 +
 
 +
With your favorite editor, create the following file
 +
 
 +
<span id="site/helloworld.php">
 +
'''<tt>site/helloworld.php</tt>'''
 
<source lang="php">
 
<source lang="php">
Hello world
+
Hello World!
 
</source>
 
</source>
 +
</span>
  
You can test this basic component by putting ''index.php?option=com_helloworld'' in your browser address (don't forget to prefix this address with your Joomla!1.6 installation path) after installing this component.
+
Yes, it is very simple but its purpose is simply to demonstrate where the entry point of the component is. After all, this is part 01.
  
=== Administrator management ===
+
=== Basic backend ===
With your favorite file manager and editor, create a file ''yoursite/administrator/components/com_helloworld/helloworld.php'' containing
+
 
<source lang="php" line>
+
You might at this point think to yourself, why are we creating a backend file when this part of the tutorial is only supposed to cover the frontend ? The answer to that question is simple, all configuration is done in the Administrator -- even though it is displayed for visitors in the frontend.
Hello world administration
+
 
 +
Joomla! will also automatically create a menu item for your component in the backend "Components" menu when the component is installed. In order to not make that link point to a page not found, we will give it a file to point to by creating a minimal backend.
 +
 
 +
With your favorite editor, create the following file
 +
 
 +
<span id="admin/helloworld.php">
 +
'''<tt>admin/helloworld.php</tt>'''
 +
<source lang="php">
 +
Hello Admins!
 
</source>
 
</source>
 +
</span>
  
You can test this basic component by putting ''administrator/index.php?option=com_helloworld'' in your browser address after installing the component.
+
=== Additional files ===
  
=== Packaging an installation zip file ===
+
In order to stay in sync with the Joomla! conventions, and to not allow misconfigured web servers to allow directory listings in our component, we also need to add the following <tt>index.html</tt> file to every folder we create within our extension structure. The purpose of this file is to simply show a blank page if someone attempts to see the directory contents by using the absolute url. Note that this is no as much as a security feature as it is a Joomla! convention which is why we stick to it, we like conventions.
If you have used Joomla before reading this tutorial, you have noticed that extensions are installed using a compressed file containing all the things which are needed for installing and uninstalling them.
+
  
 +
With your favorite editor, create the following file
  
With your favorite file manager, create a directory (outside your Joomla!1.6 installation directory) containing
+
<span id="index.html">
* ''[[#helloworld.xml|helloworld.xml]]''
+
'''<tt>index.html</tt>'''
* ''[[#site/helloworld.php|site/helloworld.php]]''
+
<source lang="html4strict">
* ''[[#index.html|site/index.html]]''
+
<!DOCTYPE html><title></title>
* ''[[#index.html|admin/index.html]]''
+
</source>
* ''[[#admin/helloworld.php|admin/helloworld.php]]''
+
</span>
* ''[[#index.html|admin/sql/index.html]]''
+
 
* ''[[#index.html|admin/sql/updates/index.html]]''
+
=== Installation manifest ===
* ''[[#index.html|admin/sql/updates/mysql/index.html]]''
+
 
* ''[[#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
+
In order for our extension to be recognized by Joomla! we also need to provide an installation xml file, also called the manifest.  
 +
 
 +
If you have chosen to create your extension in a folder outside Joomla! and thus are using the <tt>site</tt> and <tt>admin</tt> folder, the installation xml file goes right in the root of the extension folder alongside the <tt>site</tt> and <tt>admin</tt> folder. If you have chosen to create your component inside the Joomla! tree, the xml file is created inside the <tt>admin</tt> folder.
  
Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58225/com_helloworld-1.6-part01.zip archive] and install it using the extension manager of Joomla!1.6. You can test this basic component by putting ''index.php?option=com_helloworld'' or ''administrator/index.php?option=com_helloworld'' in your browser address. You can also notice that the ''Hello World!'' component is visible in the administrator site of your Joomla!1.6 installation under the ''Components'' menu.
+
With your favorite editor, create the following file
  
 
<span id="helloworld.xml">
 
<span id="helloworld.xml">
''helloworld.xml''
+
'''<tt>helloworld.xml</tt>'''
 
<source lang="xml">
 
<source lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">
+
<extension type="component" version="2.5.0" method="upgrade">
  
 
<name>Hello World!</name>
 
<name>Hello World!</name>
 
<!-- The following elements are optional and free of formatting constraints -->
 
<!-- The following elements are optional and free of formatting constraints -->
<creationDate>November 2009</creationDate>
+
<creationDate>June 2011</creationDate>
 
<author>John Doe</author>
 
<author>John Doe</author>
 
<authorEmail>john.doe@example.org</authorEmail>
 
<authorEmail>john.doe@example.org</authorEmail>
Line 49: Line 68:
 
<copyright>Copyright Info</copyright>
 
<copyright>Copyright Info</copyright>
 
<license>License Info</license>
 
<license>License Info</license>
<!--  The version string is recorded in the components table -->
+
<!--  The version string is stored in the components table -->
 
<version>0.0.1</version>
 
<version>0.0.1</version>
 
<!-- The description is optional and defaults to the name -->
 
<!-- The description is optional and defaults to the name -->
 
<description>Description of the Hello World component ...</description>
 
<description>Description of the Hello World component ...</description>
  
<update> <!-- Runs on update; New in 1.6 -->
 
<schemas>
 
<schemapath type="mysql">sql/updates/mysql</schemapath>
 
</schemas>
 
</update>
 
 
<!-- Site Main File Copy Section -->
 
 
<!-- Note the folder attribute: This attribute describes the folder
 
<!-- Note the folder attribute: This attribute describes the folder
 
to copy FROM in the package to install therefore files copied
 
to copy FROM in the package to install therefore files copied
in this section are copied from /site/ in the package -->
+
in this section are copied from "site/" in the package -->
 
<files folder="site">
 
<files folder="site">
 
<filename>index.html</filename>
 
<filename>index.html</filename>
Line 70: Line 82:
  
 
<administration>
 
<administration>
<!-- Administration Menu Section -->
 
 
<menu>Hello World!</menu>
 
<menu>Hello World!</menu>
<!-- Administration Main File Copy Section -->
 
 
<!-- Note the folder attribute: This attribute describes the folder
 
<!-- Note the folder attribute: This attribute describes the folder
 
to copy FROM in the package to install therefore files copied
 
to copy FROM in the package to install therefore files copied
in this section are copied from /admin/ in the package -->
+
in this section are copied from "admin/" in the package -->
 
<files folder="admin">
 
<files folder="admin">
<!-- Admin Main File Copy Section -->
 
 
<filename>index.html</filename>
 
<filename>index.html</filename>
 
<filename>helloworld.php</filename>
 
<filename>helloworld.php</filename>
<!-- SQL files section -->
 
<folder>sql</folder>
 
 
</files>
 
</files>
 
</administration>
 
</administration>
Line 89: Line 96:
 
</span>
 
</span>
  
<span id="site/helloworld.php">
+
As we can see, there is a lot of markup here. This is pretty much a minimal extension manifest and we will try to explain the most important bits and pieces. First off, we notice that we have an administration section, using our reasoning skills this pretty much means that whats outside the administration section is for the site application. This is not the full truth but pretty close to it.
''site/helloworld.php''
+
<source lang="php">
+
Hello World
+
</source>
+
</span>
+
  
<span id="admin/helloworld.php">
+
The <code><files></code> tag has an attribute '''folder''' which specifies which folder to look for the files in inside our extension package. Our top level extension structure has two folders <tt>site</tt> and <tt>admin</tt>. So what this tag does is tell the Joomla! installer which files to copy and to where.
''admin/helloworld.php''
+
<source lang="php">
+
Hello World administration
+
</source>
+
</span>
+
  
<span id="index.html">
+
Inside our administration section we also have a <code><menu></code> tag which simply decides which name we want to put in the Components menu in the backend when the component is installed. If we do not provide this ourselves, Joomla! will simply make a name for us based on the component name. Note that if we specify our own menu title like we do in this example, and the string does not match a language translation string (which will be covered in part 08), the alias of the menu item will be displayed in the Components menu of the administrator interface. The alias is basically the title but stripped of all special characters and having spaces replaced by hyphens. In this case "hello-world".
''index.html'' common to all folders
+
<source lang="html4strict">
+
<html><body bgcolor="#FFFFFF"></body></html>
+
</source>
+
</span>
+
  
 +
== Installation and Testing ==
  
== Installing your extension ==
+
Before testing your shiny new component you have to install it, in Joomla there are two ways of doing that, either by packaging the extension into an installable zip package or by using the discovery method. Both methods are described below but I recommend using the packaged zip file as a beginner because it is more hostile towards errors especially in the XML manifest.
  
If you have used Joomla before reading this tutorial, you have noticed that extensions are installed using a compressed file containing all the things which are needed for installing and uninstalling them. Since Joomla! 1.6 you also have the option of putting the files in the correct places inside your Joomla! installation, and discovering it using the extension manager.
+
=== Installing your component ===
 +
If you have used Joomla before reading this tutorial, you have noticed that extensions are installed using a compressed file containing all the things which are needed for installing and uninstalling them.  
  
After installlation will notice that the Hello World component is visible in the administrator site of your Joomla! installation under the Components menu.
+
A new feature made available in Joomla! 1.6 is "discover." That means you can place the files in the correct places inside your Joomla! installation, and the "Discover" option within the extension manager will install it, when selected.
  
You can test this basic component by putting index.php?option=com_helloworld or administrator/index.php?option=com_helloworld in your browser address bar.  
+
After installation will notice that the Hello World component is visible in the administrator site of your Joomla! installation under the Components menu.
  
 
=== Packaging an installation zip file ===
 
=== Packaging an installation zip file ===
Line 124: Line 118:
  
 
When you have this package, install it using the extension manager.
 
When you have this package, install it using the extension manager.
 +
 +
=== Testing your component ===
 +
 +
You can test this basic component by putting '''index.php?option=com_helloworld''' or '''administrator/index.php?option=com_helloworld''' in your browser address bar and it should show you the text that you put into the entry point files for each application respectively.
  
 
== File listing ==  
 
== File listing ==  
  
* ''[[#helloworld.xml|helloworld.xml]]''
+
* <tt>[[#helloworld.xml|helloworld.xml]]</tt>
* ''[[#site/helloworld.php|site/helloworld.php]]''
+
* <tt>[[#site/helloworld.php|site/helloworld.php]]</tt>
* ''[[#index.html|site/index.html]]''
+
* <tt>[[#index.html|site/index.html]]</tt>
* ''[[#index.html|admin/index.html]]''
+
* <tt>[[#index.html|admin/index.html]]</tt>
* ''[[#admin/helloworld.php|admin/helloworld.php]]''
+
* <tt>[[#admin/helloworld.php|admin/helloworld.php]]</tt>
  
 
== Download this part ==
 
== Download this part ==
  
[http://www.leyar.com/joomlaorg/part01.zip com_helloworld-part01.zip]
+
[https://github.com/downloads/rvsjoen/joomla-tutorials/com_helloworld-part01.zip Download example package]
  
 
== Articles in this series ==
 
== Articles in this series ==

Latest revision as of 13:43, 27 January 2012

Contents

Developing a Basic Component

Let's create a Hello World! component. All file name and path references in this tutorial are relative to the directory you are developing your extension in.

When you follow this tutorial and create files and directories you will notice that we are referring to a site folder and an admin folder. These are folders inside the component package (not in the Joomla! tree). And during installation the contents of site will be copied to the Joomla! components/com_helloworld folder and the contents of the admin folder will be copied to the Joomla! administrator/components/com_helloworld folder. If you wish to develop your extension directly in the Joomla! tree, then you may skip the site and admin folder and place the files directly in the correct folders inside the Joomla! tree. Note that if you do take this approach, you are going to have to install the component the first time using the discovery feature explained later in this part of the tutorial.

Basic frontend

When Joomla! looks for a component it will look at the option variable given in the url, in our case this will be option=com_helloworld. This means that Joomla! will look in the components directory for a folder named com_helloworld and load the file helloworld.php contained within that directory. So let us go ahead and create such an entry point.

With your favorite editor, create the following file

site/helloworld.php

Hello World!

Yes, it is very simple but its purpose is simply to demonstrate where the entry point of the component is. After all, this is part 01.

Basic backend

You might at this point think to yourself, why are we creating a backend file when this part of the tutorial is only supposed to cover the frontend ? The answer to that question is simple, all configuration is done in the Administrator -- even though it is displayed for visitors in the frontend.

Joomla! will also automatically create a menu item for your component in the backend "Components" menu when the component is installed. In order to not make that link point to a page not found, we will give it a file to point to by creating a minimal backend.

With your favorite editor, create the following file

admin/helloworld.php

Hello Admins!

Additional files

In order to stay in sync with the Joomla! conventions, and to not allow misconfigured web servers to allow directory listings in our component, we also need to add the following index.html file to every folder we create within our extension structure. The purpose of this file is to simply show a blank page if someone attempts to see the directory contents by using the absolute url. Note that this is no as much as a security feature as it is a Joomla! convention which is why we stick to it, we like conventions.

With your favorite editor, create the following file

index.html

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

Installation manifest

In order for our extension to be recognized by Joomla! we also need to provide an installation xml file, also called the manifest.

If you have chosen to create your extension in a folder outside Joomla! and thus are using the site and admin folder, the installation xml file goes right in the root of the extension folder alongside the site and admin folder. If you have chosen to create your component inside the Joomla! tree, the xml file is created inside the admin folder.

With your favorite editor, create the following file

helloworld.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">
 
        <name>Hello World!</name>
        <!-- The following elements are optional and free of formatting constraints -->
        <creationDate>June 2011</creationDate>
        <author>John Doe</author>
        <authorEmail>john.doe@example.org</authorEmail>
        <authorUrl>http://www.example.org</authorUrl>
        <copyright>Copyright Info</copyright>
        <license>License Info</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>Description of the Hello World component ...</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>helloworld.php</filename>
        </files>
 
        <administration>
                <menu>Hello World!</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>helloworld.php</filename>
                </files>
        </administration>
 
</extension>

As we can see, there is a lot of markup here. This is pretty much a minimal extension manifest and we will try to explain the most important bits and pieces. First off, we notice that we have an administration section, using our reasoning skills this pretty much means that whats outside the administration section is for the site application. This is not the full truth but pretty close to it.

The <files> tag has an attribute folder which specifies which folder to look for the files in inside our extension package. Our top level extension structure has two folders site and admin. So what this tag does is tell the Joomla! installer which files to copy and to where.

Inside our administration section we also have a <menu> tag which simply decides which name we want to put in the Components menu in the backend when the component is installed. If we do not provide this ourselves, Joomla! will simply make a name for us based on the component name. Note that if we specify our own menu title like we do in this example, and the string does not match a language translation string (which will be covered in part 08), the alias of the menu item will be displayed in the Components menu of the administrator interface. The alias is basically the title but stripped of all special characters and having spaces replaced by hyphens. In this case "hello-world".

Installation and Testing

Before testing your shiny new component you have to install it, in Joomla there are two ways of doing that, either by packaging the extension into an installable zip package or by using the discovery method. Both methods are described below but I recommend using the packaged zip file as a beginner because it is more hostile towards errors especially in the XML manifest.

Installing your component

If you have used Joomla before reading this tutorial, you have noticed that extensions are installed using a compressed file containing all the things which are needed for installing and uninstalling them.

A new feature made available in Joomla! 1.6 is "discover." That means you can place the files in the correct places inside your Joomla! installation, and the "Discover" option within the extension manager will install it, when selected.

After installation will notice that the Hello World component is visible in the administrator site of your Joomla! installation under the Components menu.

Packaging an installation zip file

Create a compressed file of your extension directory using the structure shown in the file listing section of this page or download the provided installable package.

When you have this package, install it using the extension manager.

Testing your component

You can test this basic component by putting index.php?option=com_helloworld or administrator/index.php?option=com_helloworld in your browser address bar and it should show you the text that you put into the entry point files for each application respectively.

File listing

Download this part

Download example package

Articles in this series

This tutorial is supported by the following versions of Joomla!

Joomla 2.5