PART III: The Install Package
Now that we’ve created the frontend and backend of our component we are going to do the install package that will allow us to share the component with however wants to install it.
Section 1: Organizing all the files
If you've followed Part I and Part II you now have in the folder where you've installed joomla the files containing the code of the greetings component. So the first thing you should do now is copy those files to another location, where we'll build the install package for the component. I'll refer to that location from now on as the packagefolder.
Copy the files from the frontend folder (folder where you've installed joomla/component/com_greetings) to the folder: packagefolder/site.
Copy the files from the backend folder ( folder where you've installed joomla/administrator/component/com_greetings) to the folder: packagefolder/admin.
Your packagefolder should look like this now:
├───admin
│ │ admin.greetings.php
│ │ greetingsController.php
│ │
│ ├───models
│ │ greetings.php
│ │
│ ├───tables
│ │ greetings.php
│ │
│ └───views
│ ├───greetingform
│ │ │ view.php
│ │ │
│ │ └───tmpl
│ │ greetingformlayout.php
│ │
│ └───list
│ │ view.php
│ │
│ └───tmpl
│ listlayout.php
│
└───site
│ greetings.php
│ greetingsController.php
│
├───models
│ greetings.php
│
└───views
└───greetings
│ view.html.php
│
└───tmpl
default.php
Now we have to do 5 new files:
- The XML manifest file - This will contain the the information necessary for Joomla to install the component
- The install file: This is a php file that will be executed when the component finishes installing
- The uninstall file: This is a php file that will be executed when the component finishes uninstalling
- The SQL install file: This file contains the SQL instructions necessary to set up the DB for the component
- The SQL uninstall file: This file contains the SQL instructions necessary to clean up the DB when the component is uninstalled
Let's do the easier one first, the install/uninstall files and do the XML manifest file after that.
Section 2: The installation/uninstallation files
Section 2.1: The SQL installation/uninstallation files
The SQL installation file contains the SQL that sets up the database tables that our component needs to work.
Our SQL installation file will have a comand that tests if our components table "#__greetings" (#__ is automatically replaced by the joomla database table prefix, see Section 2.4 from Part I) already exists, and if so deletes it.
The second SQL command creates the table for our greetings component.
Let's call the SQL install file install.sql and place it in packagefolder/admin/install.sql
And here's what you should put in it:
DROP TABLE IF EXISTS `#__greetings`;
CREATE TABLE `#__greetings` (
`id` int(11) NOT NULL auto_increment,
`greeting` varchar(25) NOT NULL,
PRIMARY KEY (`id`)
);
The SQL uninstall file just deletes the table that our component uses, so that if the component is uninstalled, the database table it used is also removed.
Let's call the SQL install file uninstall.sql and place it in packagefolder/admin/uninstall.sql
Here's the code for it:
DROP TABLE IF EXISTS `#__greetings`;
Section 2.2: The custom installation/uninstallation scripts
Lets start with the custom installation script. The script is executed after Joomla validates the XML manifest file (we'll do the XML manifest file in Section 3) and after all the tables in the database have been created (after the SQL install file has been executed).
The installation file we're doing just prints some text that will be displayed when you install the component, and defines a function named com_install, that will be executed by joomla. That function should return true if what we had to do in the custom installation script went well, and false otherwise. Because for this component we don't really have to do anything, we'll just return true (this function is optional, it's ok if you don't define it).
Let's call this file install.php and place it in packagefolder/admin/install.php
Here's the code for it:
<p>This is the custom install script for the Greetings Component.</p>
<p>Check the tutorial that describes this component here: <a href="http://www.joomladevuser.com" target="_blank">www.joomladevuser.com</a></p>
<?php
function com_install(){
return true;
}
?>
The uninstall script file is just like the install file. The only difference is that if you want joomla to run some custom script code that validates that everything went well with the custom uninstall script you have to define a function named com_uninstall(), that returns true when the uninstallation is successful, or false otherwise. The installation script is run before removing the tables from the DB (before executing the uninstall SQL file), basicly it's the first thing Joomla will do if you decide to uninstall the component. The definition of the com_unintall function is optional.
Let's call the custom uninstall file uninstall.php and place it in packagefolder/admin/uninstall.php
Here's the code for it:
<h3>Greetings Component</h3>
<br/>
<p>This is the custom uninstall script for the Greetings Component.</p>
<p>Check the tutorial that describes this component here: <a href="http://www.joomladevuser.com" target="_blank">www.joomladevuser.com</a></p>
<?php
function com_uninstall(){
return true;
}
?>
And that's it, now lets do the XML manifest file, that explains to Joomla how to process the install package.
Section 3: The XML Manifest file
The XML Manifest file contains the information necessary for Joomla to know how to install the component. The XML is easy to understand, but there are a few things you have to be carefull with. But before, lets have a quick look at the XML.
Name the XML manifest file com_greetings.xml and place it in the root of the package folder: packagefolder/com_greetings.xml:
<?xml version="1.0" encoding="utf-8"?>
<!--<!DOCTYPE install SYSTEM "http://dev.joomla.org/xml/1.5/component-install.dtd">-->
<install type="component" version="1.5.0">
<!-- Component name -->
<name>Greetings</name>
<!-- Optional -->
<creationDate>2008 04 28</creationDate>
<author>b1ix</author>
<authorEmail>b1ix(at)joomladevuser.com</authorEmail>
<authorUrl>http://www.joomladevuser.com</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>
<version>1.0</version>
<description>Greetings component</description>
<!-- Optional -->
<!-- Install Database Section -->
<install>
<sql>
<file charset="utf8" driver="mysql">install.sql</file>
</sql>
</install>
<!-- Uninstall Database Section -->
<uninstall>
<sql>
<file charset="utf8" driver="mysql">uninstall.sql</file>
</sql>
</uninstall>
<!-- Custom Install Script to execute -->
<installfile>install.php</installfile>
<!-- Custom Uninstall Script to execute -->
<uninstallfile>uninstall.php</uninstallfile>
<!-- Files that go to the frontend -->
<files folder="site">
<filename>greetings.php</filename>
<filename>greetingsController.php</filename>
<filename>views/greetings/view.html.php</filename>
<filename>views/greetings/tmpl/default.php</filename>
<filename>models/greetings.php</filename>
</files>
<!-- Files that go to the backend -->
<administration>
<!-- Administration Menu Section -->
<menu>Greetings</menu>
<submenu>
<menu task="display" layout="listlayout">List Items</menu>
<menu link="option=com_greetings&task=add">New</menu>
</submenu>
<!-- Administration Main File Copy Section -->
<files folder="admin">
<filename>admin.greetings.php</filename>
<filename>greetingsController.php</filename>
<filename>models/greetings.php</filename>
<filename>tables/greetings.php</filename>
<filename>views/greetingform/view.php</filename>
<filename>views/greetingform/tmpl/greetingformlayout.php</filename>
<filename>views/list/view.php</filename>
<filename>views/list/tmpl/listLayout.php</filename>
<filename>install.sql</filename>
<filename>uninstall.sql</filename>
<filename>install.php</filename>
<filename>uninstall.php</filename>
</files>
</administration>
</install>
NOTE: You can call the XML file whatever you like as long as it has a xml extension.
There are important things you have to keep in mind when doing the XML manifest file, first the name tag, you have to put the name of the component there. The lowercased name of the component is used to create the folders in the frontend and backend (com_[NAME] in our case com_greetings) and also in the option field in Joomla' components' table, also com_[NAME] (in our case com_greetings). If you don't put the name of the component there, it won't work, for example if you put in the name Greetings2 you'll get an error when accessing the component in the frontend or backend (it won't find the file: folder where you've installed joomla/components/com_greetings2/greetings2.php nor the file folder where you've installed joomla/administrator/components/com_greetings2/greetings2.php in the backend).
After you name the component with the name tag there are a set of optional tags you can use to provide aditional information about the component (creatingDate, version) and about the component's author(authorName, authorEmail, etc).
After that comes the SQL install section. In this tutorial we created separate install/uninstall sql files that create/drop the database table our component uses. When specifying which files have the SQL code (in our case install.sql and uninstall.sql) you have to specify the charset and the driver (typically mysql, I haven't used any other, so I didn't bother to look for more). There is an issue here about the charset. Any thing other than utf8 has failed to work for me. And worse, if have anything other than utf8 in the charset, the install does not produce any errors but the SQL is not executed so the database tables aren't created in the installation process and obviously your component won't work (if you know why this happens feel free to post about it in the forum).
An alternative way to specify the SQL to create/drop the component database tables for our component is to specify the SQL directly in the XML manifest file. Here's an example of how to do it:
<install>
<queries>
<query>DROP TABLE IF EXISTS `#__greetings`;</query>
<query>CREATE TABLE `#__greetings` (
`id` int(11) NOT NULL auto_increment,
`greeting` varchar(25) NOT NULL,
PRIMARY KEY (`id`)
);
</query>
</queries>
</install>
After the SQL install/uninstall files, we have the custom installation script files (install.php and uninstall.php in our case) . You can use these files to run custom script code. The custom install script code (install.php in our greetings component) is the last thing Joomla will do when installing our component (all the files will be in the right places and the database tables created). The custom uninstall script code (uninstall.php in our greetings component) will be the first thing Joomla will do when you order it to uninstall the component.
Next comes the section where you specify the files to go to the frontend of the component. You use the tag files with the attribute folder with the folder name that contains the files you specify within the <files> </files> tag.
Next comes the administration (<administration> </administration>) section. Everything you put here is relative to the backend of the component. The first part is used to specify the menus that will be available in the backend of our component.
The first tag, menu, specifies the menu item that will show up under Components in the backend. We've put Greetings as its name and when you click on it it will redirect to index.php?option=com_greetins in the backend (so the default task of the component will be executed). The submenu tag allows you to specify wich menu items will appear under your menu item under Components. As an example I've included two subitems, the List Items and New that use different submenu attributes (link, task and layout). There are more attributes you can use in the submenu. The attributes that are allowed (if you put others they will be ignored) are: link, task, layout, view, img, controller, sub, act.
Note that in the XML above, the link attribute value we have "&" instead of just having "&". We did that because the "&" character is a reserved character in XML and one of the ways to "escape" it is using & instead.
Next comes the administration files section. You have to specify the folder attribute and put there the name of the folder that contains the administrator files relative to your packagefolder (in our case the folder attribute value will be admin). And inside the <files folder="admin"> </files> you use the filename tag to specify the files that have to go to the backend. A very important note here is that the custom install/uninstall script files and SQL install/uninstall files have to be included here.
There are aditional tags you can use in the XML manifest file, namely the languages and media tags. But that will have to wait for another tutorial.
Meanwhile, if you followed all steps until now, your package folder should look like this:
│ com_greetings.xml
├───admin
│ │ admin.greetings.php
│ │ greetingsController.php
│ │ install.php
│ │ install.sql
│ │ uninstall.php
│ │ uninstall.sql
│ │
│ ├───models
│ │ greetings.php
│ │
│ ├───tables
│ │ greetings.php
│ │
│ └───views
│ ├───greetingform
│ │ │ view.php
│ │ │
│ │ └───tmpl
│ │ greetingformlayout.php
│ │
│ └───list
│ │ view.php
│ │
│ └───tmpl
│ listlayout.php
│
└───site
│ greetings.php
│ greetingsController.php
│
├───models
│ greetings.php
│
└───views
└───greetings
│ view.html.php
│
└───tmpl
default.php
The only thing missing now is zipping it all up and naming the zip file. The convention for the zip file, for components, is com_[COMPONENT_NAME]-[VERSION_NUMBER].zip. So in our case it's com_greetings-1.0.zip. And that's it! Click here to download it!
NOTE that if you followed exactly every step in these the three tutorials (component development with example I, II, III), right now you'll be in a situation where you have to uninstall the component that you've placed in joomla by "hand" (manually inserted a record in the components table, jos_components, copied the components files to the folder where you'd installed joomla, etc) before you can test the install pacakge you just did. If this is the case, when you try to uninstall it in the backend you'll get an error, something like this:
JInstaller::install: ERRORXMLSETUP
If this Extension has created tables or installed additional files, they must be removed manually.
Message:
Uninstall Component Error
Just ignore this message, it happens because the XML manifest file can't be found in the backend when you try to uninstall the component. After you see this the component is indeed uninstalled and you can now try the newly created install package.
Any comments, questions are encoraged and can be done here.
|
