The Joomla! Extensions Directory ™

Submitting Your Listing


The JED Easy Table

To help minimize confusion for what requirements are in place for listings and what is allowed/not allowed, the JED Team has created the following table.

Extension Distribution

  Allowed Not Allowed Rule Reference Invokes Editor's Note
Encryption   X TOS 1.1 N/A
Per-Domain Usage   X   N/A
Support Per-Domain X     N/A
Restrictions to Edits   X   N/A
Backlink to Developer X     X
Registration Required to Download X     X
Commercial (Cost to Download) X      
Non-Commercial (No Cost to Download) X      
Additional Framework Required X     X
Software as a Service (SaaS) X     X
Non-GPL License   X    
Promoting Features Not Included In Listed Version   X    
Require a Commercial License Key to function   X    
         
         

 

Trademark Usage Compliance

  Requires OSM Registration Requires OSM Approval Forms to Complete Related Error Codes
Domain Name using Joo, Joom, Joomla or anything similar X X TOS 1.1 TM1, UR1
Conditional Use Logos X     N/A
Limited Use Logos X X   N/A
Extension Name includes Joo, Joom, Joomla or anything similar X X   N/A
Site or product packaging uses an Altered Joomla Logo X X   N/A

 

Extension Functionality Checks

  Rule Reference Note Allowed to
Continue
Error Code
Installs through Joomla's Installer     X N/A
Extension Needs a Hack to Install       N/A
Installation Requires Manual Copy of File       N/A
Extension Hacks Core Joomla Files       N/A
Modifes other Extension Files   Must revert changes on uninstall X  
Component Admin Configuration Functions on Install     X X
Module Can be Published     X  
Plugin Can be Activated and Functions     X  
Intended for Live Sites   Alpha/Beta versions rule is under review X X
Errors Return on Install       X
Modifies folder/file Permissions without warning        
GPL Headers In all PHP Files     X  
License Tag in XML file is Correct     X  
Sanitization Statement at top of PHP files     X  
Listed on the VEL        

 

 
Error Codes for Submissions

The following list defines error codes you may see if there is an issue with your listing submission. As always, please use the JEDChecker tool to screen your extension to save time.

BL1 - Extension contains hidden backlinks.

As of September 2, 2013, hidden backlinks are not permitted in extensions listed on the JED.

ET1 - Invalid extension type.

Tools are for external applications that do not install into a Joomla site. (for example, desktop applications). Language is only for official Joomla translations.

GL1 - General listing error.

General listing don’t occur often. Please see the notes left by the JED team member. In special circumstances, you may also receive an email from a JED team member. Feel free to contact us if you have received the GL1 error message and you’d like more details.

LC1 - Licensing violation.

Every listing must comply with the current GPL License that Joomla is distributed as. Currrently, Joomla is distributed using GPL v2. There are other licenses that are compatible with the GPL v2, and those are acceptable as well. Additionally, the JED does not allow "additional restrictions" on top of the GPL. For example, you cannot limit the usage of your extension to limited number of domains. You may, however, sell "support" based on a limited number of domains.

LC2 - Extension is commercial, but doesn’t include a link to a terms of service or license agreement.

As the JED grows, new opportunities and questions arise. One issue that plagues the JED and its users is arriving at a site from a listing that is "Commercial" only to find out that additional restrictions have been placed on the extension. To help monitor this, if your listing is commercial, you must include a link to your terms of service or license agreement.

LC3 - License link does not mention extensions.

The license link provided does not mention an extension. Your license page should reference specifically how your extensions are licensed.

LC4 - Invalid license type.

Extensions are required to be GNU/GPL or AGPL licensed. LGPL is for library extensions only. Any other license type is unacceptable.

LD1 - Listing description contains a foreign language.

Listings are required to be in English. The use of any other language is not permitted.

LD2 - Your listing description contains code, tags or syntax.

Listings descriptions cannot contain code, syntax or tags as they often interfere with plugins installed in the JED.

LK1 - Invalid project link.

Project links need to point to the developer’s main site. Links to social media are not permitted.

LK2 - Invalid download link.

Download links must point directly to the download or product page. You may point directly to the file itself if registration isn’t required. Download links may not point to "Extension Installers". If you offer multiple versions of an extension (for example, a non-GPL version and a GPL version) you must only point the download link on your listing to a page that the version promoted is the one displayed on the JED.

LK3 - Demo link points to a production site.

Demo links can only point to a non-production website. It has to be an actual demo and not a live site. This field is optional and can be left blank.

LK4 - Invalid documentation link.

Documentation links need to point to actual documents about the extension. This field is optional and can be left blank.

LK5 - Invalid license link.

Commercial extensions require a link to the developer’s license on their site. Many put links to the GPL website. The requirement is just for us to ensure they aren’t adding any additional restrictions on top of the GPL. The page on their site can be as simple as “Our extensions are published under the GNU/GPL.”

LK6 - Invalid support link.

Support links need to point to a ticket system, forum or any other type of support system. This field is optional and can be left blank.

MK1 - Unapproved marketing techniques.

Promotional text (i.e. “free”) is used in the listing or a listing that is posted as non-commercial even though the extension is commercial is not permitted. If a user is requred to make a payment, like, or tweet at any point in order to use the extension it must be marked as commercial.

PH1 - Headers missing GPL license notice.

A notice is required on each PHP file stating that the file is licensed GPL (or other compatible accepted license). We recommend a format similar to:

<h3><a name="PH2"> </a>PH2 - Files missing JEXEC security.</h3>
Security is extremely important in Open Source Software, so to help prevent execution of files outside of the framework, the following code is required in all of your PHP files: {codecitation} // no direct access defined( '_JEXEC' ) or die( 'Restricted access' ); 

NM1 - Listing name does not match install name.

Listing titles/names must match the install name. Found in the install xml as:

 < name > Your aswesome extension name < /name > ) 
Using a language string for a name is not recommended.

NM2 - Listing name does not follow naming conventions for extension-specific listings.

Extension names for extensions-specific extensions must include the name of the extension that it is meant to be used with. This naming convention is in place to help protect the extension names of the

other developers. See http://docs.joomla.org/Extensions_name#Extension_Specific_Extensions for more details.

NM3 - Listing name contains “module” or “plugin”.

Extension names cannot contain the words “module” or “plugin”. See http://docs.joomla.org/Extensions_name#How_is_the_name_created_at_JED.3F for more details.

NM4 - Name/Title is a description.

Names/titles shouldn’t be a description. See http://docs.joomla.org/Extensions_name for more details.

NM5 - Version in name/title.

Versions are not permitted in names (for example: My Extension Version 1.3).

NM6 - Name already taken,

An important goal of the JED is to provide end users with the ability to find solutions easily. To maintain consistency of listings, protect copyrights and enable brands to be built, we require that all Extension/Listing Names be unique and not too similar to others already in the directory.

TM1 - Domain violation.

All domains in your listing that use a version of the trademark in the URL, must be registered and approved by Open Source Matters prior to listing approval. Also, the disclaimer required must be clearly visible on your site. This includes domains that have Joo, Joom, Joomla or something similar (for example: thejoomlasiteibuiltyesterday.com, thesiteofjoom.com, joodontknowjoomla.com, etc.).

TM2 - Extension Name Violation.

The same restrictions for domain names also apply for extension names. All extension names in your listing that use a version of the trademark in the URL, must be registered and approved by Open Source Matters prior to listing approval. However, using "Joomla XYZ Product" is not allowed (as of 2009). You may use MyProduct for Joomla as long as it's registered with OSM.

TM3 - Logo Usage Violation.

Using the Joomla logo and the requirements surrounding its usage are often confusing. To help with this, we are working on a "Simple Guide to the Joomla! Trademark". In the meantime, read the information on Open Source Matters' website concerning the Joomla! name and logo use. See http://opensourcematters.org/joomla-name-and-logo-use-requests.html for more details.

TM4 - Name/title contains a registered trademark.

The extension name contains trademarked name (for example: Instagram, Dropbox, Google Adsense, etc). The extension description should mention that trademarked names are only acceptable if the developer opens a support ticket against the submission and provides proof of authorization from the trademark holder.

TM5 - Improper fork.

The listing does not meet guidelines for forked extensions. See http://docs.joomla.org/Forked_Extensions for more details.

SE2 - Extension does not install/uninstall on a basic setup.

Every extension must install/uninstall in a basic setup. This must work on all current Joomla versions you indicate in your listing details.

SE3 - Extension is a hack.

Having a "clean upgrade path" is critical to both security and maintainability of a site. Extensions that "hack" the core or other extensions are not allowed. The only exception is if they perform the "hack" after backing up the original file, and then restoring the original file on uninstall. As nearly every extension can be installed and many have built-in "add-on installers", hacks are frowned upon more and more. Additionally, it takes extra volunteer time to review these, so the approval time could increase greatly.

SE4 - Extension modifies the permissions of files/folders without warning.

An extension that modifies folder and/or file permissions can be dangerous to a website and/or server. While it is sometimes necessary to change permissions, this must be explained during the install process so that the end user is aware of what the extension is doing to their files/server.

XM1 - License tag missing or incorrect in XML install file(s).

All install files should include the license information. In the insall XML file:

 GPL Version 

 
Setting up your Workstation for Development

This article explains one way in which you can set up your workstation for writing Joomla! extensions. It assumes that you are using Eclipse and that you are familiar with using Eclipse for working with Joomla! and Subversion. For more information about the basics of getting started with Eclipse for Joomla! development, see Setting up your workstation for Joomla! development. Note that these instructions assume you are using XAMPP version 1.7 or later.

Joomla! developers can and do use many different development tools, and there is no one way that is best for everyone. This article documents one way to use Eclipse and Phing to help streamline the process of writing and testing Joomla! extensions.

[edit]Overview

If you are writing a Joomla! extension, you have a challenge. On one hand, you need to keep the source code for the extension separate from the Joomla! source code. However, you also need to be able to run and perhaps debug the extension from within Joomla!. The problem is somewhat more difficult if you are using the Subversion (SVN) source code control system for the extension source code.

One simple way to do this is to create two separate projects in Eclipse. One project will be the "development" project. It will only contain the extension source code, and, if needed, can be controlled by SVN. The second project will be a "test" project. It will contain a full copy of Joomla! as well as a copy of your extension source code. Then we will create a Phing automatic build task that will allow us to keep the test copy of the extension current with the actual development copy.

[edit]Create the Development Project

The development project will contain the source code just for your Joomla! extension. If you are using SVN, then you will create this project in Eclipse by using File → Import → Checkout Projects from SVN. If you are not using SVN, you will just create a new PHP Project and create the appropriate folders and files for the extension. You should also have an install archive file so you can install the extension in Joomla! using the normal extension installer (Extensions → Install/Uninstall). We will see below how we can use Phing to create ZIP and "tar.az" archives automatically.

In our simple example, our extension is a plugin called "FJ Author Plugin". This has just two files called "authorunpublish.php" and "authorunpublish.xml". We also have created a zip archive file that contains these files, so we can install this extension on a Joomla! website.

[edit]Create the Test Project

Creating the test project is very easy. Just create a new PHP Project in Eclipse (in our case, called "Joomla_1.5.19_test"). Then unzip a full Joomla! zip archive into the top-level folder for this project (in our example, "C:\xampp\htdocs\joomla_development\Joomla_1.5.19_test"). Then navigate to the back end of this site and install Joomla!. (Note: If you already have a test environment set up you can just use this environment.)

Once the environment is set up, install the current version of the extension into the Joomla! test site in the normal way. In the back end of Joomla!, navigate to Extensions → Install/Uninstall, press Browse, find the archive file for your extension, and press "Upload File and Install".

  • Note that this step is needed so that the Joomla! installer can add the extension to the database. In this case, a row is added in the jos_plugins table to register this plugin in Joomla!.
  • Also note that, at this stage, the extension programs do not have to be working or finished. You just have to have a valid XML file for the installation and the appropriate files. The contents of the files, other than the XML file used for installation, does not matter. They can even be empty files.
    • Sample XML:
<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="authentication">
    <name>Authentication - Myauth</name>
    <author>Joomla! Documentation Project</author>
    <creationDate>May 30, 2007</creationDate>
    <copyright>(C) 2005 - 2007 Open Source Matters. All rights reserved.</copyright>
    <license>http://www.gnu.org/copyleft/gpl.html GNU/GPL</license>
    <authorEmail>
 This e-mail address is being protected from spambots. You need JavaScript enabled to view it
 </authorEmail>
    <authorUrl>www.joomla.org</authorUrl>
    <version>1.5</version>
    <description>An sample authentication plugin</description>
    <files>
        <filename plugin="myauth">myauth.php</filename>
    </files>
    <params/>
</install>

[edit]Install Phing

Next, we need to add the Phing program to our PHP environment. Phing is an open-source project build system based on Apache Ant. In this example, we are going to use it to automate the copying of the program files from the development project to the test project every time we build the project.Download Phing

Installing Phing is very easy.

  1. Go to the command line.
  2. Change directory to the Apache PHP folder. On my XAMPP system, it is "C:\xampp\php".
  3. Enter the command pear channel-discover pear.phing.info
  4. Then enter the command pear install phing/phing
  5. The system will download Phing. On Windows, the executable "BAT" file will be in your PHP folder (for example, "C:\xampp\php").

If phing is already installed, you may see the error "Ignoring installed package phing/phing Nothing to install" at step 4.

In some cases, the version of Phing that is included with XAMPP may not work correctly. (For example, I had this problem running XAMPP 1.7 on Windows Vista.) The symptom of this problem is that you will get an error message "No VERSION.TXT file found" when you try to run a Phing script. If this happens, uninstall and then re-install Phing as follows:

  1. at the command prompt, enter pear uninstall phing/phing
  2. then enter pear install phing/phing

[edit]Install Phing at Linux

You need to have pear package for php installed.

  1. At opensuse 11.3 run under root user:
    zypper install php5-pear-VersionControl_SVN php5-pear-xml_parser php5-pear
    

    This will install 3 packages, but I guess, php5-pear will be enough.
  2. Run:
    sudo pear channel-discover pear.phing.info
    

    My result was:
    pear channel-discover pear.phing.info
    Adding Channel "pear.phing.info" succeeded
    Discovery of channel "pear.phing.info" succeeded
  3. Run
    pear install phing/phing
    

    My result was:
    # pear install phing/phing
    Unknown remote channel: pear.phpunit.de
    Did not download optional dependencies: phing/phingdocs, channel://pear.phpunit.de/PHPUnit, pear/PhpDocumentor, pecl/Xdebug,
    pear/PEAR_PackageFileManager, use --alldeps to download automatically
    phing/phing can optionally use package "phing/phingdocs" (version >= 2.4.2)
    phing/phing can optionally use package "channel://pear.phpunit.de/PHPUnit" (version >= 3.4.0)
    phing/phing can optionally use package "pear/PhpDocumentor" (version >= 1.4.0)
    phing/phing can optionally use package "pecl/Xdebug" (version >= 2.0.5)
    phing/phing can optionally use package "pear/PEAR_PackageFileManager" (version >= 1.5.2)
    downloading phing-2.4.2.tgz ...
    Starting to download phing-2.4.2.tgz (369,282 bytes)
    ............................................................................done: 369,282 bytes
    install ok: channel://pear.phing.info/phing-2.4.2

[edit]Create the "build.xml" File

Next, we need to create a file called "build.xml". This file will tell Phing what we want it to do during a project build -- in our case, just copy the two plugin files from the development project to the test project.

In Eclipse, select File → New → XML and create a file called "build.xml" in the root folder of your extension project. In our example, the file will contain the following code:

<?xml version="1.0" encoding="UTF-8"?>
<project name="FJ Author Plugin" default="copy_all" basedir=".">
        <property name="src"   value="."/>
        <property name="test"  value="../Joomla_1.5.9_test/plugins/content" />
        <target name="copy_all" description="Copies files to test project.">
                <echo message="Running build.xml. Copying files from dev to test..." />
                <copy file="${src}/authorunpublish.php" todir="${test}"/>
                <copy file="${src}/authorunpublish.xml" todir="${test}"/>
        </target>
</project>

Line 2 tells Phing that the default action to take is called "copy_all" and that the base directory for this is the current directory. Lines 3 and 4 just define the variables "src" (our current development folder) and "test" (where we want the files to be copied). Notice that "test" is set to copy the files to the "plugins/content" folder of the Joomla! test system. Of course, this will vary with different extension types. You can define as many variables as you need.

The next line creates the "target" element, in this case the default target called "copy_all". Inside the target element we have three lines. The first is just an echo command which will display the message in the Eclipse console when the build is run. The next two actually do the work. They copy the two files from the "src" folder to the "test" folder.

There are many things you can do inside a build file with Phing. See the Phing User Guide for more information.

[edit]Add Phing to the Eclipse Build

The last step is to set up the project in Eclipse so that our Phing build program is run automatically each time we build the project. To do this:

  1. Right-click on the project and select Properties. Then select "Builders" as shown below.
  2. Press New to display the Choose Configuration Type dialog shown below.
  3. Select Program and press OK to show the Edit Configuration dialog shown below.
    • In the Name field, enter a descriptive name for the program.
    • In the Location field, press "Browse File System" and browse to the location of the "phing.bat" file (for example, "c:\xampp\php").
    • In the Working Directory, press "Browse Workspace" and select the root folder of the current project.
    • Note that we are not entering anything into the Arguments field. This is because Phing by default will run the file called "build.xml". Also, we specified the "copy_all" as the default task inside the "build.xml" file. So this executes by default when Phing is run.
  4. Click on the Refresh tab to display the screen below.
    Here you have the option of refreshing the workspace after the files are copied.

    Note about Eclipse Refresh: Eclipse keeps track of all local file changes. This allows it to restore files from it's local history repository. When you copy or change files outside of Eclipse (for example, with Phing), Eclipse needs to record these file changes. This is done with the Refresh command.

    If you check the options "Refresh resources upon completion" and "The entire workspace", then the workspace will be automatically refreshed after the build. On some systems, this might take a long time. In this case, you would uncheck the "Refresh resouces upon completion" box. If automatic refresh is not done, you just need to refresh the files (using F5 or right-click → Refresh) manually. If you try to open a file that hasn't been refreshed, you get a message "Resource is out of sync with the file system" and you can refresh at that time.
  5. Press the Build Options tab to show the screen below.
    Here you can choose whether to have the Phing script run "During auto builds". If you set the project up for Automatic Builds (using the menu option Project → Build Automatically), and you check the "During auto builds" option, the Phing script will be run automatically every time you save an edited file.
  6. Press OK and the Properties dialog should now be as shown below.

Finally, let's test that this works. The idea here is that our Phing task should run whenever we build the Eclipse project. In the PHP Explorer, right-click on the project and select "Build" (this option only appears when 'Build Automatically', found in the Project menu, is turned off). In the Eclipse console, you should see something similar to screen below.

[edit]No VERSION.TXT Error

If you get the error "No VERSION.TXT file found; try setting phing.home environment variable.", you may need to uninstall and re-install Phing. See Install Phing above for more information.

Note that, in this example, the source files in the development project were identical to the files in the test project, so we got the message "omitted, is up to date" for both. If you change one or both of these files and build the project again, you will see they have been copied.

[edit]Can't load default task list Error

If you get the Error "BUILD FAILED Can't load default task list" you may need to add the PEAR data path to the PHP include path. To do so open php.ini form your PHP installation folder (e.g. C:\xampp\php\), locate the line with the "include_path" setting and add the data folder (e.g.

include_path = ".;C:\xampp\php\PEAR;C:\xampp\php\PEAR\data

[edit]More Phing Examples

Below are some more examples of things you can do with Phing. Please keep in mind that there are many advanced capabilities that you can use with Phing. See the Phing website for more information.

[edit]Run Phing File Outside of Build

In the previous example, we ran the Phing build.xml file automatically when the Eclipse project was built. We can also run any Phing file directly from Eclipse using the Eclipse External Tools Configuration. To do this:

  1. Select Run → External Tools → External Tools Configuration, as shown below.
  2. Highlight the Program option and click on the New Launch Configuration button, as shown below.
  3. Fill out the Externals Tools Configurations dialog box as shown below.
    • Enter a descriptive name in the Name field.
    • In the Location field, again click on the Browse File System button and find the "phing.bat" file.
    • In the Working Directory field, click on the Browse Workspace button and select the root directory of the project.
    • In the Arguments field, enter "-f build.xml". Note that this is not strictly necessary, since "build.xml" is the default file name for Phing. However, this shows how you would run any Phing file.
  4. Select the Refresh tab and enter the desired refresh options. These are the same as discussed earlier.
  5. Select the Build tab to show the screen below.
    Here you can select whether or not you want to automatically build the project before running this Phing script and, if so, which projects you want to build.
  6. Press the Run button to actually run the "build.xml" file. You should see the same output as you did when you ran the project build.

To re-run this file, you can just select it from the list using the Run External Programs button, as shown below.

Alternatively, you can select Run → External Tools and select it from that list.

[edit]Copy From Test Project to Development Project

In some situations, it may be more convenient to write your code in the test environment and copy files from the test project to the development project. Again, this is very easy to do with Phing. In this example, we will create a Phing file in our development project called "copy_to_dev.xml" that will copy the files from our test project to the development project.

  1. Highlight the test project (in our example, "Joomla_1.5.9_test"), right-click, and select New → XML.
  2. Place the file in the project's root directory and name it "copy_to_dev.xml".
  3. In our example, the code for this file is the following:
<?xml version="1.0" encoding="UTF-8"?>
<project name="Plugin Test" default="copy_to_dev" basedir=".">
        <property name="test"   value="./plugins/content"/>
        <property name="dev"  value="../FJ Author Plugin" />
        <target name="copy_to_dev" description="Copies files to dev project.">
                <echo message="Copying files from test to dev..." />
                <copy file="${test}/authorunpublish.php" todir="${dev}"/>
                <copy file="${test}/authorunpublish.xml" todir="${dev}"/>
        </target>
</project>
This code is very similar to the "build.xml" discussed above, except that it copies in the other direction.

To run this, add a new External Tools Run Configuration by following the steps outlined in the previous section. When you get to the External Tools Configurations dialog, enter the following in the Arguments field: -f copy_to_dev.xml. Check that the settings in the Refresh and Build tabs are what you want. For example, you may want to uncheck the "Build before launch" option if it takes a long time to build the test project.

When you run this, it should copy the files from the test project to the development project.

[edit]Alternate Copy File Syntax

Another way to use Phing to copy files is using the "fileset" property. The script below does the same thing as the "build.xml" file shown earlier.

<?xml version="1.0" encoding="UTF-8"?>
<project name="FJ Author Plugin" default="copy_all" basedir=".">
        <property name="test"  value="../Joomla_1.5.9_test/plugins/content" />
 
    <!-- Fileset for all files -->
    <fileset dir="${project.basedir}" id="allfiles">
        <include name="authorunpublish.*" />
    </fileset>
 
    <!-- copy_all Target -->
    <target name="copy_all" description="copy all files target">
        <echo message="Copying files to test project..." />
        <copy todir="${test}">
            <fileset refid="allfiles" />
        </copy>
    </target>
</project>

This code uses the Phing "fileset" property to select the files to be copied. With this property, you can include or exclude files using wildcards to create the list of files you need. You can read more about different Phing options at the Phing web site.

[edit]Create Archive Files In Phing

You can also use Phing to automate the creation of your extension archive files. For example, the script below creates a "tar.gz" archive using the built-in "tar" task in Phing:

<?xml version="1.0" encoding="UTF-8"?>
<project name="FJ Author Plugin" basedir="." default="copy">
 
    <property name="testdir" value="../Joomla_1.5.9_/plugins/content" override="true" />
    <property name="srcdir"   value="${project.basedir}" override="true" />
 
    <!-- Fileset for all files -->
    <fileset dir="." id="allfiles">
        <include name="authorunpublish.*" />
    </fileset>
 
    <!-- Copy Target -->
    <target name="copy" description="copy target">
        <echo>Running phing_test.xml. Copying files from dev to test...</echo>
        <copy todir="${testdir}">
            <fileset refid="allfiles" />
        </copy>
        <echo msg="Creating archive..." />
        <tar destfile="plg_authorunpublish.tar.gz" compression="gzip">
            <fileset refid="allfiles" />
        </tar>
        <delete file="plg_authorunpublish.zip" quiet="true" />
        <zip destfile="plg_authorunpublish.zip">
            <fileset refid="allfiles" />
        </zip>
         <echo msg="Files copied and archive file created OK!" />
        </target>
</project>

Notice that we can re-use the "fileset" we used for the copy task. The "tar" task creates a compressed "tar.gz" archive for our extension. The "zip" task creates a zip archive. Also note that we have a "delete" task before the "zip" task. This is because the zip task adds files to the archive instead of replacing files in the archive.

[edit]More Complex Phing Example

Here is a more complicated real-life example of a Phing script. The project is called FJEventsNews and has the following structure, typical of a simple Joomla! component extension:

Our Phing script will do two things:

  1. Copy each of these files to the appropriate folder in the test project (called JEvents_dev).
  2. Create a ZIP and "tar.gz" archive file for installation.

Here is the script:

<?xml version="1.0" encoding="UTF-8"?>
<project name="FJEventsNews" basedir="." default="copy_to_test">
 
        <property name="test" value="../Jevents_dev" override="true" />
        <property name="testadmincomp"
                value="../Jevents_dev/administrator/components/com_fjeventsnews"
                override="true" />
        <property name="src" value="${project.basedir}" override="true" />
        <fileset dir="./site" id="component_files">
                <include name="**" />
        </fileset>
        <fileset dir="${src}" id="allfiles">
                <include name="admin/*" />
                <include name="language/*.*" />
                <include name="language/admin/*.*" />
                <include name="site/helpers/*" />
                <include name="site/models/*" />
                <include name="site/views/fjeventsnews/tmpl/*.*" />
                <include name="site/views/fjeventsnews/*.*" />
                <include name="site/views/*.*" />
                <include name="site/*.*" />
                <include name="fjeventsnews.xml" />
        </fileset>
 
        <!-- Copy Target -->
        <target name="copy_to_test" description="copy target">
                <echo>Copying files from dev to test...
                </echo>
                <copy file="${src}/admin/admin.fjeventsnews.php" 
                        todir="${testadmincomp}" />
                <copy file="${src}/admin/index.html" todir="${testadmincomp}" />
                <copy file="${src}/language/admin/en-GB.com_fjeventsnews.ini"
                        todir="${test}/administrator/language/en-GB" />
                <copy file="${src}/language/en-GB.com_fjeventsnews.ini" 
                        todir="${test}/language/en-GB" />
                <echo msg="Copying site files if needed..." />
                <copy todir="${test}/components/com_fjeventsnews">
                        <fileset refid="component_files" />
                </copy>
                <copy file="${src}/fjeventsnews.xml" todir="${testadmincomp}" />
                <delete file="${src}/com_fjeventsnews_dev.zip" />
                <zip destfile="${src}/com_fjeventsnews_dev.zip">
                        <fileset refid="allfiles" />
                </zip>
                <tar destfile="${src}/com_fjeventsnews_dev.tar.gz" compression="gzip">
                        <fileset refid="allfiles" />
                </tar>
        </target>
</project>

This script uses the same commands we have seen in the earlier examples. It is just longer because we are working with more files. Here are some notes about the script:

  • The first three property elements just define variables we will use later in the script.
  • We define two "fileset" elements.
    • The first one, called "component_files", is used to copy all of the files under the "site" folder to the test folder, "components/com_fjeventsnews".
    • The second "fileset" element is "allfiles". We use this to create the two archive files. Notice that this uses "*.*" in some places. This is to exclude folder names. If the "*" is used, for example, in "site/*", then empty folders are included in the ZIP archive and this causes errors in the Joomla! extension install. By using "*.*", we only include files, since all of the files have extensions.
    • Notice also that we can have multiple include statements. We could also use "exclude" statements if we needed them to exclude one or more files or folders.
  • This file only has one "target" element, which is the default target. If we wanted, we could break this up into two or more "target" elements and execute them separately. Then we could use the command arguments -f filename targetname to call a specific target. For example, if we had a target in the file called "create_archive", we could enter -f copy_to_test.xml create_archive to execute the "create_archive" target instead of the default "copy_to_test" target.

As stated earlier, there are many more advanced capabilities of Phing which are documented in the Phing website.

[edit]Inserting Version Control Info in Your Files

If you ever edited one of Joomla's files you might certainly have noticed a comment block at the top of the file like this:

/**
* @version      $Id: index.php 10381 2008-06-01 03:35:53Z pasamio $
* @package      Joomla
* @copyright    Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license      GNU/GPL, see LICENSE.php
* Joomla! is free software. This version may have been modified pursuant
* to the GNU General Public License, and as distributed it includes or
* is derivative of works licensed under the GNU General Public License or
* other free or open source software licenses.
* See COPYRIGHT.php for copyright notices and details.
*/

What we are going to address here is the very first line of that block.

Note that it contains the name of the file, the build number of the last time the file was committed, the date and time of the last commit and the username of the person who committed the file.

The question is: "How can I use it in my own SVN managed extension project?"

Actually, it's quite easy to accomplish with the keyword replacement feature in SVN that we will explain here!

The first step is to put a comment block like the one above in your file. Actually, you don't have to use the same structure as the files in Joomla, but it would be better to maintain consistency and to make possible for your extension to be documented by phpDOC like the Joomla! 1.5 API Reference. But, to achieve our goal, it's enough to have a comment block like:

/**
* $Id$
*/

Notice the two "$" signs and the uppercase "I" letter. Place this comment block in every file you want to have the keyword replacement to take place. It doesn't matter where you put the block, but the top of the file seems to be more logical.

After placing the comment block in all the files, you are ready for the replacement to occur, but SVN won't do anything without being explicitly told to. So, let's move to next step.

For the keyword replacement to occur, it's necessary to instruct SVN through a special property named "svn:keywords". Notice that this property applies only to files, not folders, so you have to set it for each and every file you want to have the replacement to take place, just as you did with the comment block. Also, never set this property for binary files. If you do, Eclipse may behave oddly when you make a commit.

To do it just highlight the file you want to set the property for.

If the file isn't versioned yet you'll have to make it versioned to be able to set the property. For this, right-click the file and select Team → Add To Version Control. You'll see that a blue plus sign will appear at the bottom-right-hand of the file's icon.

Now it's time to set the property for the file. At the bottom of the edit area, there's a set of tabs. One of them might read "SVN Properties". Select that tab, right click inside of it and select "Add a Property" from the menu. If this tab isn't showing you can always right-click the file and choose Team → Set Property.

In the window that opens just type svn:keywords for the property's name and Id (notice the capitalized I letter) in the "Enter a text property" text box. Select OK.

You're set. Next time you make a commit, right after finishing the commit process, SVN will replace the $Id$ tag in your comment block with all the information you see in Joomla! files. Also, after committing the first time, if anybody else makes a change to that file and commits it, the next time you update your working copy the changes will be reflected in the comment block.

There is a quicker way to set the property for a set of files at once. Instead of highlighting each file, highlight the folder that contains them. Then proceed as explained above with the difference that in the "Set Property" window you'll have to check the "set property recursively" select box at the bottom of the window. In this case, make sure the folder doesn't contain any binary files for the reason we mentioned before. If inadvertedly you set the property for a binary file, just select the file/files, right-click svn:keywords property in the "SVN properties" tab and delete it.

For more information about SVN properties, check Version Control with Subversion - Chapter 9

[edit]Tips

  • If you accidentally overwrite or delete a file, remember that Eclipse automatically keeps a local history of all files in a project. You can right-click on any file and select either Compare With → Local History or Replace With → Local History to recover any lost edits.
  • If you delete a file and need to restore it, you can right-click on a project and select Restore From Local History. This will let you recover any deleted files.
  • If you have multiple Phing scripts, including a "build.xml" script, you may need to check the setting "Build before launch" on the Build tab of the External Tools Configuration. For example, if this is checked for a Phing file called "copy_to_test.xml", the "build.xml" will be run each time you run "copy_to_test.xml", which may not be what you want.
  • On Windows Vista, you might see the error message "CLI Has Stopped Working". This error doesn't cause any problems, but it is annoying. This error comes from a bug in the file c:\xampp\php\ext\php_mysqli.dll that is included with some versions of XAMPP. You can correct this error as follows:

 
My Listing Was Rejected

Some of the common reasons extensions are rejected are because of:

  • logo violations
  • extension cannot be downloaded or found on the site
  • extension does not install
  • Listing remained pending in the approval queue for over 60 days with error codes
 
Installation and Functionality

 

This article is designed to help Extension Developers, JED Editors (consistence for extensions approval) and general users (on reporting JED entries).

To be approved and listed in JED an entry must be verified in a 4 steps checklist process

  • You are now in fourth step

List D1 - Installation

Could this be installed with Joomla?
Item What? Publishable?
1 Install with Joomla installer? YES!
  • Some specific extensions are installed by extension special installer
2 Extensions needs a hack to install? No
3 Extensions needs manual copy file to install? No
  • Exceptions available for Payment systems
4 Extensions hacks Joomla files? No
  • Please contribute with code to Joomla Core
5 Extensions changes other extension files? Only if the changes are reverted upon uninstall
  • Extension hacks are not allowed!

 

List D2 - Basic Functionality

This is not intended for a full test thet should be performed by developers and users.

Does it works in a Joomla site?
Item What? Publishable?
1 Component configuration on Admin Menu works? YES!
2 Module can be published? YES
3 Plugin can be activated and site/article its working? YES
  • Legacy plugin requires a note on Joomla! version compatibility
4 In the component, is it possible to add a new item/category/file? YES
5 Intended for public sites? No
  • Latest version cannot be a "test only" version

 

List D3 - Security

This is not intended for a full security test.

Does it presents a security risk?
Item What? Publishable?
1 Listed at Vulnerable Extensions List NO!
2 Permissions: requires a 777 permission to install or run NO!
3 Sanitized: statement for Restricted access at top of the PHP files? YES!

See

 

List D4 - Uninstall

Does it breaks a Joomla site?
Item What? Publishable?
1 After uninstall, Site or Admin returns errors? NO!


Everything OK? Publish extension!

 

TOC: JED Submissions Checklists

Table of Contents

 
«StartPrev123NextEnd»

Page 1 of 3