ARTIO JoomSEF Documentation

version 1.4.0-beta
compatible with Joomla 1.0.x
by ARTIO s.r.o.
last updated on 11th of January 2007

Table of contents

  1. Introduction
  2. Licence
  3. Installing and Configuring
    1. Installation
    2. Configuring IIS
    3. Uninstall
    4. Configuration Checklist
    5. Non-latin languages
    6. Automatic Updates
  4. Useful Usage Tips
  5. Supported Joomla! Components
    1. Joomla! Built-in Components
    2. 3rd Party Components
    3. List of Official Extensions Available
    4. Extension installation
  6. Support and Help
  7. Donate to JoomSEF
  8. Advertisement Notice
  9. Change log
  10. Credits
  1. Introduction

    ARTIO JoomSEF is a Joomla! component that generates and allows creation of Search Engine Friendly (SEF) URLs for Apache and IIS, returns proper 404 status code for missing content, provides logging of 404 errors, and creation of special "shortcut" URLs that allow the user to redirection to the new URL.

    Starting with version 1.3.0 JoomSEF also allows control of specific meta tags, such as description or keywords for each generated URL. JoomSEF comes with SEF support for most popular Joomla! components. Some of those are delivered free as part of the JoomSEF instllation package and some are also available under commerial licence. If you are missing a support for your favourite component, ARTIO may develop it on request.

    This documents describes how to install and setup ARTIO JoomSEF Joomla! component. You can view this documentation again by selecting the "ARTIO JoomSEF Documentation" button from the ARTIO JoomSEF Control Panel.

  2. Licence

    This software is distributed under GNU General Public Licence. By installing and using this software, you agree to bind to the licence conditions.

    Please note that some add-on parts for this software (component and module extensions) may be available under other (commercial) licence conditions.

  3. Installing and Configuring

    You can view installation instructions below by clicking the appropriate arrow.

    If your .htaccess file was set as writable the install may have updated it already and you shouldn't have to worry about it.

    If your site is in a subdirectory be sure to change the RewriteBase line accordingly. ex/ RewriteBase /joomla

    1. Installation

      1. Upload the zip file to Joomla! using the component installer in the usual way.
      2. For apache, set your ".htaccess" file like this:
        ##
        # @version $Id: htaccess.txt 2368 2006-02-14 17:40:02Z stingrey $
        # @package Joomla
        # @copyright Copyright (C) 2005 Open Source Matters. All rights reserved.
        # @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
        # Joomla! is Free Software
        ##
        
        
        #####################################################
        #  READ THIS COMPLETELY IF YOU CHOOSE TO USE THIS FILE
        #
        # The line just below this section: 'Options FollowSymLinks' may cause problems
        # with some server configurations.  It is required for use of mod_rewrite, but may already
        # be set by your server administrator in a way that dissallows changing it in
        # your .htaccess file.  If using it causes your server to error out, comment it out (add # to
        # beginning of line), reload your site in your browser and test your sef url's.  If they work,
        # it has been set by your server administrator and you do not need it set here.
        #
        # Only use one of the two SEF sections that follow.  Lines that can be uncommented
        # (and thus used) have only one #.  Lines with two #'s should not be uncommented
        # In the section that you don't use, all lines should start with #
        #
        # For Standard SEF, use the standard SEF section.  You can comment out
        # all of the RewriteCond lines and reduce your server's load if you
        # don't have directories in your root named 'component' or 'content'
        #
        # If you are using a 3rd Party SEF or the Core SEF solution
        # uncomment all of the lines in the '3rd Party or Core SEF' section
        #
        #####################################################
        
        #####  SOLVING PROBLEMS WITH COMPONENT URL's that don't work #####
        # SPECIAL NOTE FOR SMF USERS WHEN SMF IS INTEGRATED AND BRIDGED
        # OR ANY SITUATION WHERE A COMPONENT's URL's AREN't WORKING
        #
        # In both the 'Standard SEF', and '3rd Party or Core SEF' sections the line:
        # RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] ##optional - see notes##
        # May need to be uncommented.  If you are running your Joomla! from
        # a subdirectory the name of the subdirectory will need to be inserted into this
        # line.  For example, if your Joomla! is in a subdirectory called '/test/',
        # change this:
        # RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] ##optional - see notes##
        # to this:
        # RewriteCond %{REQUEST_URI} ^(/test/component/option,com) [NC,OR] ##optional - see notes##
        #
        #####################################################
        
        
        ##  Can be commented out if causes errors, see notes above.
        Options FollowSymLinks
        
        #
        #  mod_rewrite in use
        
        RewriteEngine On
        
        
        #  Uncomment following line if your webserver's URL
        #  is not directly related to physical file paths.
        #  Update Your Joomla! Directory (just / for root)
        
        # RewriteBase /
        
        
        ########## Begin Standard SEF Section
        ## ALL (RewriteCond) lines in this section are only required if you actually
        ## have directories named 'content' or 'component' on your server
        ## If you do not have directories with these names, comment them out.
        #
        #RewriteCond %{REQUEST_FILENAME} !-f
        #RewriteCond %{REQUEST_FILENAME} !-d
        #RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] 		##optional - see notes##
        #RewriteCond %{REQUEST_URI} (/|\.htm|\.php|\.html|/[^.]*)$  [NC]
        #RewriteRule ^(content/|component/) index.php
        #
        ########## End Standard SEF Section
        
        
        ########## Begin 3rd Party or Core SEF Section
        #
        #RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] 		##optional - see notes##
        RewriteCond %{REQUEST_URI} (/|\.htm|\.php|\.html|/[^.]*)$  [NC]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule (.*) index.php
        #
        ########## End 3rd Party or Core SEF Section
        							
      3. For IIS, see Configuring IIS.
      4. Ensure that SEF is enabled under Global Configuration in the Joomla! backend.
      5. Edit the JoomSEF configuration, Change Enable to yes and save.
        This is neccessary to ensure the default 404 document gets saved to the Joomla! database.
    2. Configuring IIS

      Since JoomSEF 1.3.2 support for IIS servers has been retested and updated.

      JoomSEF has been succesully tested on IIS5 and IIS6. As the installation process is quite complex, we provide just the basic hints here. If you have problems setting this up, please contact our support team (please note that the support is a paid service).

      1. Configure PHP as ISAPI filter

        In your IIS website configuration, configure PHP to run as ISAPI filter. JoomSEF will probably not work with CGI versions correctly.
      2. Install ISAPI Rewrite Filter

        To make JoomSEF work on your IIS you will further need a rewrite component similar to mod_rewrite to Apache. There is several of them available free or commercial. Staying with free solutions, it works e.g. with ISAPI_Rewrite Lite. From the others IISRewrite or SAPI_Rewrite Full should be ok. We have also tested it with IIRF (Ionic's ISAPI Rewrite Filter) but this one was a bit buggy, although closes to the original Apache's mod_rewrite (hopefully author can fix it soon).
        Download the choosen component and follow its documentation to install it .
      3. Create IIRF .ini file

        Create an .ini with rewrite rules for the rewrite components. This is analogy of the Apache's .htaccess. The rules needed may differ on component choosen, your server configuration and your usage needs. If you are unsure about configuring this (or also any of the previous steps), you may contact your support.
        In general you may copy the rules from the htaccess.txt file disctributed with Joomla! and adjust them to match the rewrite component possibilities. E.g. for every RewritingRule, add [L,U] modifier.
        If your Joomla! installation is not located in the website root, you will need to add the relative path to all the RewriteRules. (to simulate Apache's RewriteBase setting). If your Joomla! is located directly in the web site root, just add "/" before the index.php in the 2nd part of the RewriteRules.
        An example configuration for IIRF for the site located in subdirectory /joomla/demo would be following:
        ########## Begin 3rd Party or Core SEF Section
        #
        RewriteCond %{URL} ^(/component/option,com) [NC,OR] 		##optional - see notes##
        RewriteCond %{URL} (/|\.htm|\.php|\.html|/[^.]*)$  [NC]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule /joomla/demo/(.*) /joomla/demo/index.php [L,U]
                                    
      4. Configure the Custom Errors (optional)

        NOTE: in the example below, Joomla! is installed in the virtual directory Joomla!
        Using the Internet Services Manager, right-click the directory in which Joomla! is installed.
        Select properties >> Custom Error
        set the 404 to URL:/joomla/index.php
        set the 405 to URL:/joomla/index.php
    3. Uninstall

      1. Uninstall the component using the component unistaller in the usual way.
      2. For apache, set your ".htaccess" like this:
        ##
        # @version $Id: htaccess.txt 2368 2006-02-14 17:40:02Z stingrey $
        # @package Joomla
        # @copyright Copyright (C) 2005 Open Source Matters. All rights reserved.
        # @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
        # Joomla! is Free Software
        ##
        
        
        #####################################################
        #  READ THIS COMPLETELY IF YOU CHOOSE TO USE THIS FILE
        #
        # The line just below this section: 'Options FollowSymLinks' may cause problems
        # with some server configurations.  It is required for use of mod_rewrite, but may already
        # be set by your server administrator in a way that dissallows changing it in
        # your .htaccess file.  If using it causes your server to error out, comment it out (add # to
        # beginning of line), reload your site in your browser and test your sef url's.  If they work,
        # it has been set by your server administrator and you do not need it set here.
        #
        # Only use one of the two SEF sections that follow.  Lines that can be uncommented
        # (and thus used) have only one #.  Lines with two #'s should not be uncommented
        # In the section that you don't use, all lines should start with #
        #
        # For Standard SEF, use the standard SEF section.  You can comment out
        # all of the RewriteCond lines and reduce your server's load if you
        # don't have directories in your root named 'component' or 'content'
        #
        # If you are using a 3rd Party SEF or the Core SEF solution
        # uncomment all of the lines in the '3rd Party or Core SEF' section
        #
        #####################################################
        
        #####  SOLVING PROBLEMS WITH COMPONENT URL's that don't work #####
        # SPECIAL NOTE FOR SMF USERS WHEN SMF IS INTEGRATED AND BRIDGED
        # OR ANY SITUATION WHERE A COMPONENT's URL's AREN't WORKING
        #
        # In both the 'Standard SEF', and '3rd Party or Core SEF' sections the line:
        # RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] ##optional - see notes##
        # May need to be uncommented.  If you are running your Joomla! from
        # a subdirectory the name of the subdirectory will need to be inserted into this
        # line.  For example, if your Joomla! is in a subdirectory called '/test/',
        # change this:
        # RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] ##optional - see notes##
        # to this:
        # RewriteCond %{REQUEST_URI} ^(/test/component/option,com) [NC,OR] ##optional - see notes##
        #
        #####################################################
        
        
        ##  Can be commented out if causes errors, see notes above.
        Options FollowSymLinks
        
        #
        #  mod_rewrite in use
        
        RewriteEngine On
        
        
        #  Uncomment following line if your webserver's URL
        #  is not directly related to physical file paths.
        #  Update Your Joomla! Directory (just / for root)
        
        # RewriteBase /
        
        
        ########## Begin Standard SEF Section
        ## ALL (RewriteCond) lines in this section are only required if you actually
        ## have directories named 'content' or 'component' on your server
        ## If you do not have directories with these names, comment them out.
        #
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        #RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] 		##optional - see notes##
        RewriteCond %{REQUEST_URI} (/|\.htm|\.php|\.html|/[^.]*)$  [NC]
        RewriteRule ^(content/|component/) index.php
        #
        ########## End Standard SEF Section
        
        
        ########## Begin 3rd Party or Core SEF Section
        #
        #RewriteCond %{REQUEST_URI} ^(/component/option,com) [NC,OR] 		##optional - see notes##
        #RewriteCond %{REQUEST_URI} (/|\.htm|\.php|\.html|/[^.]*)$  [NC]
        #RewriteCond %{REQUEST_FILENAME} !-f
        #RewriteCond %{REQUEST_FILENAME} !-d
        #RewriteRule (.*) index.php
        #
        ########## End 3rd Party or Core SEF Section
        							
    4. Configuration Checklist

      Make sure that:

      1. the .htaccess exists in the root of your Joomla! site
      2. the 3rd party section rules in .htaccess are uncommented
      3. the "RewriteBase" rule matches YOUR Joomla! installation
      4. Joomla! SEF is "ON" in site "Global configuration"
      5. JoomSEF is "ON" in site "JoomSEF configuration"

    5. Non-latin languages

      If your web site uses non-lating languages (such as greek, hebrew, etc.), make sure to configure the character conversion map correctly in JoomSEF Configuration / Non-ascii character replacements for all characters your language is using.

      The format you need to use is oldChar1|newChar1,oldChar2|newChar2,... .
      Example: α|a,β|b,γ|c,...

    6. Automatic Updates

      Starting with version 1.3.0, JoomSEF provides automatic updates capabilities.

      Thanks to this feature, it is no longer needed to uninstall and install the component each time you want to upgrade to higher version. After activating the automatic upgrade tool in the JoomSEF control panel, the component will check, whether newer version is available on-line and if yes, it will automatically download it and install rewriting your current version.

  4. Useful Usage Tips

    Configuration

    Using the ARTIO JoomSEF configuration is fairly straight forward. For more information on each item hover your mouse over the blue (i) images when you are in the configuration screen.

    When you save the configuration it will remove all your URL's from the database. If you have a high traffic site it may be wise to put it offline before saving the ARTIO JoomSEF config or purging the database and go and browse your site starting at the main page. This will create the URL's properly for you and prevent numbers from being added to the ends of URL's people were browsing that changed.

    You may want to purge the 404 log before creating fresh urls.

    Optimization

    To achieve maximum performance, you should consider several things.

    Always have the lates JoomSEF version installed as we continue optimizations with every release.

    Enable Joomla! caching.

    Use JoomSEF Configuration to turn SEF off for those components you do not need it or which generate too many unoptimized links. Typically when you note links like 45.html, 46.html, ..., something is probably wrong.

    JoomSEF will always be a DB-driven SEO component. It will produce very nice and highly editable URLs for you, but for the cost of higher load for your DB. When configured properly and cached, the load increase should not be significant, but especially with big and frequently visited sites, pay a special attention to configuration and installed modules and plan your SEO carefully.

    Modifying URL's

    You can modify URL's to your liking. Go into the ARTIO JoomSEF Control Panel and click ' View/Edit SEF Urls'. Select the URL you wish to modify. If you click the check box labeled 'Save as Custom Redirect' it will place this URL into the 'Custom Redirect' area which you can navigate to from the ARTIO JoomSEF Control Panel. When you click 'View/Edit Custom Redirects' you will see your URL in here now instead. These urls will not be removed when you save the config. You can modify these and save them as you wish.

    This is particularly useful if you are updating from an old site because any URL's that are no longer availble will be logged. You can view these URL's by clicking 'View/Edit 404 Logs' in the ARTIO JoomSEF Control Panel. You can redirect visitors to the new page by selecting the URL you wish to modify and entering the new url. Note: The ability to enter non-Joomla! URL's into this area is coming soon! This will allow you to easily transfer a non-Joomla! site to Joomla using ARTIO JoomSEF and any of your old URL's will be redirected to the new page within Joomla!.

    Backing up your URL's

    It is recommended to backup your database before doing this.

    You can also import and export URL's from the Custom Redirect area. To do this click the 'Import/Export Custom URLS' link above the table of URL's. To backup your URL's click the 'Backup Custom URLS' button and you will be presented with a file named 'ARTIO JoomSEF_custom_urls.sql' to download.

    If you want to import your urls browse to the file and click the 'Import Custom URLS' button.

  5. Supported Joomla! Components

    Joomla! Built-in Components

    The support for Joomla! core components, such as banners, content, contacts, news, newsfeeds, weblinks, etc. is already integrated in the JoomSEF component. Optimization of URLs for these components requires no further efforts.

    3rd Party Components

    The situation is slightly different for 3rd party components. There exists many 3rd party components and modules for Joomla!, which usually differ significantly in complexity and structure. This means that for some of those (usually the simple ones), the SEO will work using the the default JoomSEF component handler. The others (usually more complex ones) may cause problems when used with the default handler. Such problems may include errors, loss of functionality, insufficient SEO, or generation of duplicate URLs. These can be either skipped in JoomSEF Control Panel, so no SEF URLs will be generated for them, or will require a special "extensions".

    Extensions are special pieces of code for JoomSEF, written with particular 3rd party component in mind (e.g. VirtueMart, JoomlaBoard, ...}. Such extension can be either part of the component/module self (provided by component/module author), may come as part of JoomSEF installation package or be provided by 3rd parties. ARTIO offeres most of such extensions available for free as part of the JoomSEF distribution package. However, some of the extensions are provided also under commercial licence. Bellow, you may find list of official extenstions available for JoomSEF.

    List of Official Extensions Available

    • AlphaContent (free)
    • DocMan (free)
    • JoomlaBoard (free)
    • Jomres (on request)
    • Mosets Tree (free)
    • SMF Bridge (Simple Machines Forum) (payed)
    • VirtueMart (payed)
    • Zoom Galery (free)

    We hope this list will be spread fast. Our priority is to add support for the most popular extensions first. If you haven't found your favourite component/module here and it does not work with JoomSEF correctly, you may contact us and we may develop a needed extension for you.

    Extension Installation

    To install extra SEF extension for a component, use installer accessible from the JoomSEF Control Panel.

    1. Click "Install" tool in the toolbar
    2. Use "Upload file" box to select an extension installation file and press "Upload and Install" button
    3. If everything went ok, you should get an confirmation screen with installation status; after clicking "Continue..." link, your new SEF extenstion is ready to use

  6. Donate to JoomSEF

    ARTIO JoomSEF is a free software. However the development costs are same as for any other software. If you are satistifed with this software and you would like us to implement new features, fix the bugs promptly and publish new releases regularily, you can send us a donation and thus support the JoomSEF further development.

    You may do so via PayPal service using your credit card or transfer, or you can send us the payment directly.

    Bank account information:
    Recieving Bank: Ceskoslovenska obchodni banka (CSOB)
    Address: Hollarova 5, Ostrava, Czech Republic
    Account No.: 199371035, Bank code: 0300
    SWIFT: CEKOCZPP
    IBAN: CZ1303000000000199371035

  7. Support & Help

    If you need more help with the ARTIO JoomSEF component, visit our webpages at http://www.artio.cz and check our FAQs & support forums.

  8. Advertisement Notice

    JoomSEF may add user-invisible links pointing to websites of JoomSEF authors (ARTIO s.r.o.) and/or to its sponsors. Such links appear in page footers or meta tag fields of pages, where it is used. This has no direct influence to functionality of your site.

    Similarily to Joomla! software, these may be removed if you wish to do so. However, by keeping them, you help us develop the software further and increase the number of users.

  9. Changelog

    v1.4.0

    11th January 2007
    • Significant improvement of OpenSEF and SEF Advance extensions
    • Added option to ignore link sources to reduce # of link to 1 target
      Please note that switching this feature on may affect Joomla functionality
    • Added option to reappend source information as anchor
      Please note that switching this off when previous in on may affect Joomla functionality
    • Fixed pagination problems when not possible to reach first page
    • Other small fixes

    v1.3.3

    11th January 2007
    • Higher user comfort (edited URLs are automatically saved as "custom")
    • Protecting from unwanted URL list deletion on configuration change

    v1.3.2

    10th January 2007
    • Revised, retested and updated IIS support
    • Fixed problems when switching between http and https (VirtueMart checkout problem)
    • Documentation updates
    • Several other small bugs fixes

    v1.3.1

    5th December 2006
    • Upgrade module bugfix
    • Other small bug fixes

    v1.3.0

    28th November 2006
    • Added upgrade capability
    • Added AlphaContent support
    • Added Mosets Tree support
    • Added VirtueMart component support (payed)
    • Added SMF Bridge v1.1 RC3 component support (payed)
    • Added URL filters in admin section
    • Added title, description and keywords metatags for individual URLs
    • Fixed lower-case URL problem with components excluded from JoomSEF processing
    • Duplicate home URL fix
    • Other small bug fixes

    v1.2.5

    18th September 2006
    • Significantly updated JoomFish support
    • Added possibility to add language to URL as path or suffix
    • Added possibility to translate URLs using JoomFish
    • Removed duplicities in URLs (Google indexing optimizaiton)
    • Enabled defining of own non-ascii characters rewrite rules
    • Fixed number of minor bugs

    v1.2.4

    31st August 2006
    • Documentation update.
    • Prevented loadClass error problem with older Joomla! versions.

    v1.2.3

    29th August 2006
    • Compatibility fix with URLs using numeric entities (e.g. generated by JCE WYSIWG editor).

    v1.2.2

    28th August 2006
    • Security fixes to match Joomla 1.0.11 requirements and minor bugs coorections.

    v1.2b

    15th August 2006
    • Fixed pagination problems.
    • Integrated JoomFish and DocMan support.
    • Ported from original version.
  10. Credits

    ARTIO s.r.o.
    Mrstikova 840/6
    Ostrava - Marianske Hory
    70900 Czech Republic

    http://www.artio.net
    info@artio.net

    Michal Unzeitig, team leader
    David Jozefov, developer
    Petr Vlasak, developer

Copyright © 2006 ARTIO s.r.o.
Distributed under the terms of the GNU General Public License.