## JoomSEF User Manual

version 3.4.0
by ARTIO s.r.o.
last updated on 16. October 2009

## Table of contents

1. Introduction
2. Licence
3. Installing and Configuring
   1. Installation
   2. Configuring IIS
   3. Uninstall
   4. Upgrading from free to paid version
   5. Configuration Checklist
   6. Non-latin languages
   7. Automatic Updates
4. Useful Usage Tips
   1. Configuration
   2. Optimization
   3. Preventing duplicates
   4. Cache
   5. Patch System
   6. JoomFish Support
   7. Component Configuration
   8. Modifying URLs
   9. Metadata and Page Titles Organization - JoomSEF Metabot
   10. Backing up your Custom URLs
5. Supported Joomla! Components
   1. Joomla! Built-in Components
   2. 3rd Party Components
   3. List of Official Extensions Available
   4. Extension Downloads
   5. Extension Installation
   6. Extension Upgrade
   7. Extension Parameters
6. Support and Help
7. Donate to JoomSEF
8. Advertisement Notice
9. 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 installation package and some are also available under commercial 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 following licensing conditions. By installing and using this software, you agree to bind to the licence conditions. Author reserves right to change these conditions at any time without prior notice.

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 should not 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. If not processed automatically by installer (e.g. due to write restriction to file), adjust your .htaccess file. Please note, that some directives may not be supported with specific web server or dependant on its configuration. See the comments in file for details.

         Unsupported directives in .htaccess file are most common cause for seeing "500 Internal Server Error" message after JoomSEF installation.

      3. For Apache, set your ".htaccess" file like this (this is file for Joomla 1.5.x):

             ##
             # @version $Id: htaccess.txt 9975 2008-01-30 17:02:11Z ircmaxell $
             # @package Joomla
             # @copyright Copyright (C) 2005 - 2008 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 disallows 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.
             #
             #####################################################

             ##  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 - Joomla! core SEF Section
             #
             RewriteCond %{REQUEST_FILENAME} !-f
             RewriteCond %{REQUEST_FILENAME} !-d
             RewriteCond %{REQUEST_URI} !^/index.php
             RewriteCond %{REQUEST_URI} (/|\.php|\.html|\.htm|\.feed|\.pdf|\.raw|/[^.]*)$  [NC]
             RewriteRule (.*) index.php
             RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
             #
             ########## End - Joomla! core SEF Section

             ########## Begin - Rewrite rules to block out some common exploits
             ## If you experience problems on your site block out the operations listed below
             ## This attempts to block the most common type of exploit `attempts` to Joomla!
             #
             # Block out any script trying to set a mosConfig value through the URL
             RewriteCond %{QUERY_STRING} mosConfig_[a-zA-Z_]{1,21}(=|\%3D) [OR]
             # Block out any script trying to base64_encode crap to send via URL
             RewriteCond %{QUERY_STRING} base64_encode.*\(.*\) [OR]
             # Block out any script that includes a <script> tag in URL
             RewriteCond %{QUERY_STRING} (\<|%3C).*script.*(\>|%3E) [NC,OR]
             # Block out any script trying to set a PHP GLOBALS variable via URL
             RewriteCond %{QUERY_STRING} GLOBALS(=|\[|\%[0-9A-Z]{0,2}) [OR]
             # Block out any script trying to modify a _REQUEST variable via URL
             RewriteCond %{QUERY_STRING} _REQUEST(=|\[|\%[0-9A-Z]{0,2})
             # Send all blocked request to homepage with 403 Forbidden error!
             RewriteRule ^(.*)$ index.php [F,L]
             #
             ########## End - Rewrite rules to block out some common exploits

         For older Joomla versions (1.0.x) see the original file in the website root (htaccess.txt), rename it to .htaccess and follow the comments within. Htaccess file for Joomla 1.0.x contains 2 rewrite rules sections. With JoomSEF installation, the latter must be uncommented (by default, it is commented out).

      4. For IIS, see Configuring IIS.
      5. Ensure that SEF is enabled under Global Configuration in the Joomla! backend.
      6. Edit the JoomSEF configuration, Change Enable to yes and save.
         This is necessary 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 successfully tested on IIS5 and IIS6. As the installation process is rather complex, we provide just the basic steps and 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. (recommended)

      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, both free or commercial. Staying with free solutions, it works e.g. with ISAPI_Rewrite Lite. From the others IISRewrite or ISAPI_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 chosen component and follow its documentation to install it.

      3. #### Create rewrite rules definition file

         Create an .ini with rewrite rules for the rewrite components. The name of file and location may differ based on selected rewrite module. For ISAPI_Rewrite the file name is httpd.ini and should be store in the modules install directory. For details for your module check its documentation.

         The file analogy of the Apache's .htaccess. The rules needed may differ on component chosen, your server configuration and your usage needs. If you are unsure about configuring this (or also any of the previous steps), you may contact our support.

         In general you may copy the rules from the htaccess.txt file distributed with Joomla! and adjust them to match the rewrite component possibilities. Please note that every module has a slightly different set of rules that it supports. (e.g. ISAPI_Rewrite does NOT support %{REQUEST_FILENAME} !-f) and existing files need to be checked by other rule. E.g. for every RewriteRule, 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.

         Specific configuration may differ with different IIS Rewrite modules used and its versions (Helicon Isapi Rewrite 2 or 3) and also with Joomla versions 1.0 or 1.5.

         An example configuration for IIRF for the site located in subdirectory /joomla/demo would be following:

             ########## Begin - Joomla! core SEF Section
             #
             RewriteCond %{REQUEST_FILENAME} !-f
             RewriteCond %{REQUEST_FILENAME} !-d
             RewriteCond %{REQUEST_URI} !^/index.php
             RewriteCond %{REQUEST_URI} (/|\.php|\.html|\.htm|\.feed|\.pdf|\.raw|/[^.]*)$  [NC]
             RewriteRule /joomla/demo/(.*) /joomla/demo/index.php
             RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
             #
             ########## End - Joomla! core SEF Section

             ########## Begin - Rewrite rules to block out some common exploits
             ## If you experience problems on your site block out the operations listed below
             ## This attempts to block the most common type of exploit `attempts` to Joomla!
             #
             # Block out any script trying to set a mosConfig value through the URL
             RewriteCond %{QUERY_STRING} mosConfig_[a-zA-Z_]{1,21}(=|\%3D) [OR]
             # Block out any script trying to base64_encode crap to send via URL
             RewriteCond %{QUERY_STRING} base64_encode.*\(.*\) [OR]
             # Block out any script that includes a <script> tag in URL
             RewriteCond %{QUERY_STRING} (\<|%3C).*script.*(\>|%3E) [NC,OR]
             # Block out any script trying to set a PHP GLOBALS variable via URL
             RewriteCond %{QUERY_STRING} GLOBALS(=|\[|\%[0-9A-Z]{0,2}) [OR]
             # Block out any script trying to modify a _REQUEST variable via URL
             RewriteCond %{QUERY_STRING} _REQUEST(=|\[|\%[0-9A-Z]{0,2})
             # Send all blocked request to homepage with 403 Forbidden error!
             RewriteRule ^(.*)$ index.php [F,L]
             #
             ########## End - Rewrite rules to block out some common exploits

      #### 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. Restore your .htaccess file to the default version (see htaccess.txt) or remove it completely - depending on whether you will continue to use Joomla! default SEO or not.

   4. ### Upgrading from free to paid version

      If you have purchased a paid version of JoomSEF and you want to replace the free one without loosing the current configuration and already stored SEF URLs, please follow this procedure:

      1. from JoomSEF control panel, choose "Upgrade"
      2. from upgrade page, choose "Install from page"
      3. choose the installation file you have download from ARTIO website
      4. click the upgrade button

   5. ### 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"

   6. ### Non-latin languages

      If your web site uses non-latin 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,...

   7. ### Automatic Updates

      Starting with version 1.3.0, JoomSEF provides automatic updates capabilities. From version 2.0.x automatic upgrades also apply to JoomSEF extensions.

      Thanks to this feature, it is no longer needed to uninstall and install the component each time you want to upgrade to newer 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

   1. ### 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.

   2. ### Optimization

      To achieve maximum performance, you should consider several things.

      Always have the latest 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.

      If certain component is using pagination, sorting and similar parameters an advanced configuration option "Append non-SEF variables to URL" may significantly reduce a number of SEF links generated and thus also your DB load. However, please note that the excluded variables will be reappended to your URL in standard form as &varname=value.

      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.

   3. ### Preventing duplicates

      If you are facing duplicate content items links e.g. http://yoursite.you/article.html, http://yoursite.you/article-2.html, etc. that lead to the same content, this is most probably caused by so called "Itemid" variable (although there may be other reasons also).

      The Itemid is internal Joomla! variable used to identify the source of a URL link. E.g. main menu or sub menu item that your visitor used to get to a certain content. According to this variable, different Joomla! configurations are applied - e.g. what template will be used or what modules will be visible, etc.

      Since JoomSEF 1.4.0, several new configuration options are provided in "Advanced configuration" section. The option "Exclude source info" may be used to exclude the Itemid variable from the URL and thus eliminate the duplicates caused by it. However, ignoring it completely may lead to unwanted Joomla! functionality, like not switching the templates as desired or so. Whether this will be a problem for you or not depends mainly on the way how your site is designed and how complicated it is. If you need to fix this, the Itemid should be "reappended" to the SEF URL as an extra part using the option "Reappend source". Then the resulting URL will look http://yoursite.you/article.html&Itemid=xy.

      Since JoomSEF 2.0.0 there is a possibility to set your own Itemid for each extension that will always be used with it - thus even when "Reappend source" is set to Yes, that extension won't have the ?Itemid=xy appended. You can find this option in extension parameters. If you leave the "Override Itemid" field blank, the default Itemid will be used, but won't be appended as ?Itemid=xy in URL. Thus you can achieve that the ?Itemid=xy will be added only to those extensions that need it (mostly content). But be careful, setting Itemid to some random number can ruin your menu functionality!

      Another new option is "Ignore multiple sources". If selected, only one URL will be created for each page using the first Itemid. Every other link varying in Itemid only will be ignored and the already created one will be used instead. But again - this can ruin your menu functionality! This option has no effect on extensions with custom Itemid set.

   4. ### Cache

      JoomSEF 2.0.0 introduces own cache functionality to decrease the amount of queries to your database. You can find this option in Advanced Configuration section.

      When caching is enabled, the most often used links will be kept in memory and will not require querying database every time. You can set the cache size (how many links can be stored in memory) and minimum hit count - only links with hit count greater than specified value will be stored in cache. Be careful about the cache size option - the more links in cache means less queries to database, but on the other hand bigger memory consumption.

   5. ### Patch System

      JoomSEF 2.0.0 also comes with the new Patch System. This will also decrease amount of queries made to database because everyone can use only those patches he needs, so no more "SELECT DATABASE()" queries if you use only one database.

      A patch is basically a mambot specifically designed to work with JoomSEF only. This means that you can use default Joomla! Mambot installer to manage these patches. Also every patch you install must be published in Site Mambots section in order to work.

   6. ### JoomFish Support

      There are several ways you can let JoomSEF build URLs on your multi-lingual site. They are displayed in JoomFish Related Configuration section of JoomSEF configuration when JoomFish is installed.

      Language integration

      - Include in path - with this option selected your URLs will look like www.mysite.com/en/somepage.html
      - Add as suffix - this option will make your URLs look like www.mysite.com/somepage_en.html
      - Use different domains - useful option if you have several domains registered for your site. Resulting URLs will look like http://en.mysite.com/somepage.html
      - Do not add - does not add any language code to URLs. Should be used only when "Translate URLs" option is active or it will create duplicate links.

      Always use language
      With this option active the language code will always be added to resulting URL. This may decrease duplicate links count as there won't be two links (with and without language code) pointing to the same page.

      Translate URLs
      Activate to have your URLs translated using JoomFish - this will improve the readability of your URLs for people preferring other languages.

      Domain Configuration
      Here is the place to set custom domain for each language if you have Use different domains selected.

   7. ### Component Configuration

      In the Component Configuration section of JoomSEF configuration you can set some options for each component individually.

      Handling
      Controls the way how links are processed.

      - Use default handler - JoomSEF will try to create the best looking URL it can using all available resources.
      - Nocache - JoomSEF will create URLs the same way as default Joomla! SEF does - they won't be stored in database and will look like www.mysite.com/component/option,com_virtuemart/Itemid,50/
      - Skip - JoomSEF will not process URLs at all and they will look as with the SEF disabled entirely.

      Custom title
      Lets you set your own extension title to use in URL instead of default menu title. Leave blank for default one. If you use JoomFish you can also translate these custom titles.
      When checking the check box next to the custom title box, the menu title part of the URL will be left empty.

   8. ### Modifying URLs

      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 available 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!.

   9. ### Metadata and Page Titles Organization - JoomSEF Metabot

      To organize and adjust your site metadata (such as title, meta desc, meta keywords, etc.] from one place, you may use features offered by JoomSEF Metabot. Metabot is installed as a standard Joomla! system mambot (plugin in Joomla 1.5.x) and takes care about composition of your page title and meta data in the page head section.

      Metabot will load the metadata you have defined for a certain SEF URL using the JoomSEF URL editor and will place them into the head section of your current Joomla! page.

      Hint: To define title and/or meta tags for your homepage (that has not really an URL generated by SEF, but composes just from your site base URL), create a new entry in the URL list where the SEF URL will stay blank and the original URL will say just index.php.

      For metabot, to work correctly, it must be used always with JoomSEF component and it has to be in published state. Metabot has also several user configurable option, such as the way how page / site name in page titles is organized and other metadata related settings. To access this configuration, find the ARTIO Metabot in installed Joomla mambots (plugins) list and click it. The configurable parameters then can be found on the right side of the mambot (plugin) detail page.

   10. ### Backing up your Custom URLs

       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

   1. ### 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.

   2. ### 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 may work fine, while for other, you can experience, problems such as disfunctionality, 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".k 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 fun

      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 extensions available for JoomSEF.

   3. ### List of Official Extensions Available

      To get the list of the latest JoomSEF extensions available, please, visit the JoomSEF official website.
      We hope this list will spread fast. Our priority is to add and maintain support for the most popular extensions. If you haven't found your favourite component here and it does not work with JoomSEF correctly, please, let us know.

   4. ### Extension Downloads

      JoomSEF extensions can be free or paid. Many free extensions can be downloaded directly from ARTIO downloads section or from authors' websites. ARTIO also publishes paid extensions that are available from ARTIO webshop.

   5. ### 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 extension is ready to use

   6. ### Extension Upgrade

      If a new version of extension becomes available, you can update it using JoomSEF Online Upgrade function (if released by ARTIO) or by downloading the recent version and reinstalling it (by uninstalling the old and reinstalling the new version; existing URLs will be maintained).

   7. ### Extension Parameters

      Since JoomSEF 2.0.0 each extension can have its own parameters affecting resulting URLs - you can access them through main JoomSEF's administration page using the Edit button in the toolbar or simply clicking on extension's name.

6. ## Donate to JoomSEF

   ARTIO JoomSEF is a free software. However the development costs are same as for any other software. If you are satisfied with this software and you would like us to implement new features, fix the bugs promptly and publish new releases regularly, 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:
   Receiving 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.net and check our FAQs & support forums.

8. ## Advertisement Notice

   Free edition of JoomSEF may add 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 and you will NOT be penalized by search engines for it.

   You may also purchase a commercial version of JoomSEF that DOES NOT contain these advertisement links. This component is available from ARTIO on-line store.

9. ## Credits

   ARTIO s.r.o.
   Mrstikova 840/6
   Ostrava - Marianske Hory
   709 00 Czech Republic
   http://www.artio.net
   info@artio.cz

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