Fri, 29 August 2008
Home
Articles
Books
Search
Tools
Whois
Links
Sitemap
Contact us
Privacy policy
Home arrow Articles arrow Mambo arrow Mambo Component Tutorial

Mambo Component Tutorial PDF Print E-mail
Articles - Mambo
Article Index
Mambo Component Tutorial
Frontend files
Administration files
Class files
Installation files
Appendix A. mosMenuBar
Appendix B. getPath
Page 5 of 7
Installation files
Installation files are only used during installation (or uninstallation) process to copy/delete files and images to (or from) the correct locations, create (or delete) database tables used by your component, and display your installation (or uninstallation) messages. Files in this group are copied to installdir/administrator/components/mycomp folder.

  • mycomp.xml
    This file contains details about your component (name, version, copyright, your URL & email, etc), the list of files and images used, SQL commands to be executed during install/uninstall, and list of menu items to appear in administration page (under 'Components' menu).

    Your component name (the text between <name></name>) will be used as directory name after it is converted to lowercase, all the spaces removed, and prefixed with 'com_'. So 'My Component' will be saved in 'com_mycomponent' directory, etc. Therefore it is better to avoid using non-alphanumeric characters in component name.

    Below is a sample of the XML file for our hypothetical component 'My Component'. I will only explain some of the tags since most are self-explanatory.

    <?xml version="1.0" ?>
    <mosinstall type="component">
      <name>My Component</name>
      <creationDate>01/02/2005</creationDate>
      <author>Your Name</author>
      <copyright>(c) 2005 Company</copyright>
      <authorEmail> </authorEmail>
      <authorUrl>www.domain.com</authorUrl>
      <version>1.0</version>
      <description>
        Description of this component
      </description>

      <files>
        <filename>mycomp.php</filename>
        <filename>mycomp.html.php</filename>
      </files>

      <images>
        <filename>img/img1.gif</filename>
        <filename>img/img2.gif</filename>
      </images>

      <install>
        <queries>
          <query>
            CREATE TABLE #__mycomp_data(
              id int unsigned not null,
              name varchar(255) not null,
              PRIMARY KEY (id)
            ) TYPE=MyISAM;
          </query>
          <query>
            (another query, etc)
          </query>
        </queries>
      </install>

      <installfile>
        install.mycomp.php
      </installfile>

      <uninstallfile>
        uninstall.mycomp.php
      </uninstallfile>

      <uninstall>
        <queries>
          <query>DROP TABLE #__mycomp_data;</query>
          <query>(another query, etc)</query>
        </queries>
      </uninstall>

      <administration>
        <menu>My Component</menu>
        <submenu>
          <menu act="config">Config</menu>
          <menu act="manage">Manage Items</menu>
        </submenu>

        <files>
          <filename>admin.mycomp.php</filename>
          <filename>admin.mycomp.html.php</filename>
          <filename>toolbar.mycomp.php</filename>
          <filename>toolbar.mycomp.html.php</filename>
        </files>

        <images>
          <filename>img/img3.gif</filename>
          <filaname>img/img4.gif</filename>
        </images>
      </administration>
    </mosinstall>

    All files in <files></files> and <images></images> will be copied to installdir/components/mycomp while those in <administration></administration> will be copied to installdir/administrator/components/mycomp.

    SQL queries in <install></install> are executed during installation while those in <uninstall></uninstall> are executed during uninstall. Table name format used is #__mycomp_tablename where #_ will be replaced by Mambo to whatever table prefix you select during Mambo installation. By default the prefix is 'mos' so '#__mycomp_data' will create a table named 'mos_mycomp_data'.

  • install.mycomp.php (optional)
    This file contains only 1 function, com_install(), which will be called after successful installation of your component. Examples of what you can put here is congratulation message, copyright information, link to your website, etc.

    <?php
    function com_install() {
        return     'Installation successful! Please check my website for the latest update and support.';
    }
    ?>

    Please take note that com_install() expects you to return the message, not echo it directly from within the function, to display it in the correct position on the success page. Here is the difference:

    Message from com_install

    While it's not harmful to echo from inside the function, it's not politically correct either :-)

  • uninstall.mycomp.php (optional)
    As with install.mycomp.php, this file also contains only 1 function, com_uninstall(). As with com_install(), com_uninstall() also expects you to return the message. Mambo is supposed to display this message after uninstalling a component but strangely I have never seen message from this file displayed.

    <?php
    function com_uninstall() {
        return     'My Component is successfully removed from Mambo';
    }
    ?>

Well, that wraps up our component tutorial. The following 2 pages contains lists of toolbar functions and keys used by $mainframe->getPath() function. For further reading, Joseph LeBlanc also has a tutorial on his website.



 

Powered by
Syndicate