Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Realurl/manual

From TYPO3Wiki
Jump to: navigation, search

<< Back to Extension manuals page

[edit]

This is the wiki version of the manual for realurl

notice - Note

Please check what content of this page is new. Improvements made on this page should be merged into the manual.


RealURL

Extension Key: realurl

Copyright 2003-2016

Martin Poelstra & Kasper Skårhøj & Dmitry Dulepov

notice - Open Content License

This document is published under the Open Content License

The content is related to TYPO3 - a GNU/GPL CMS/Framework available from typo3.org


Introduction

What does it do?

The extension provides automatic transformation of URLs with GET parameter in the frontend (like "index.php?id=123&type=0&L=1") into a virtual path, a so called "Speaking URL" (like "dutch/contact/company-info/page.html") and back again. The objective is that URLs shall be as human readable as possible.

The extension is very flexible and can provide from simple translation of page IDs to encoding of almost any possible combination of GET parameters.

Background

TYPO3 works with page-IDs. This works great, however the URLs are ugly ("...index.php?id=123&type=0&L=1...." etc.). There are workarounds (simulateStaticDocuments), but that's just a fake: the ID must still be supplied in the URL, which is not desirable. Furthermore, only the page-title is shown, not the complete 'path' (or 'rootline') to the page.

Normally, you type in the path and filename of a document, but TYPO3 works exclusively with page IDs. The RealURL extension provides a way to translate between page IDs and (virtual) URLs that are easy to read and remember.

The extension requires the Apache module "mod_rewrite" to rewrite the virtual URLs of the site to the TYPO3 frontend engine.

Generally it will work out-of-the-box but you will have to address the issue that all media referenced in the HTML page has to have either absolute URLs or the <base> tag set. Both methods have advantages and drawbacks, but the bottomline is that you might have to adjust your templates/coding at various places to be compatible.

Features

  • Supports various schemes for coding the page path, including userdefined schemes
  • Pagetitles can contain spaces and characters like /.,&@ etc; the URL will still be nice.
  • URLS are generated as nice-looking lowercase paths
  • If a page is renamed, the old URL can still be used (see below in the Users Manual), so if the page was indexed by e.g. Google, it can still be found.
  • Offers advanced translation of almost any set of GET parameters to/from virtual URL
  • Translation between a GET query string ("...&tx_myext[blabla]=123&type=2...") and a virtual URL (".../123/2/") is transparent to TYPO3 and all extensions; the only requirement is that the internal TYPO3 link generation functions are used ("ContentObjectRenderer::typolink", "TemplateService::linkData")
  • URLs are cached, so translating between URLs and IDs is very fast.
  • It can handle different page types
  • URLs are multilingual: if you're browsing in Dutch, you'll see Dutch URLs
  • Once configured the system works fully automatic, creating new and updating existing URLs
  • You can easily see where shortcuts are pointing to, as the 'target' URL is generated, instead of the URL to the shortcut itself.
  • It automatically handles multiple domains in the database
  • It automatically handles installations of TYPO3 in directories other than the root of the website too

RealURL 1.x did not have any usable configuration defaults. Everybody knows that configuring RealURL 1.x is a pain. RealURL 2.x provides reasonable defaults and requires minimal information from the user. With RealURL 2.0 you can avoid configuration completely if you have domain records on proper pages or a single root page with "Is site root?" flag set in page properties.

Requirements inside TYPO3

There are certain constraints and requirements that must be followed to ensure that RealURL works correctly. If any of them are not met, correct behavior cannot be guaranteed.

  • There must be no "nested domains". This means that there can be only one domain record from the current page down to the root of the page tree. RealURL does not support nested domains!
  • Each root page of the site must have a "Use as Root page" option checked. This option is located on the Behavior tab of page properties.
  • There must be no pages with the same name on one level for the same parent page. In particular this means you cannot have "News" page and "News" sysfolder under the same parent page. Having pages with the same name under one parent page this will not resolve URLs correctly. "Name" here means page title, alias, navigation title or RealURL path segment field.
  • If you have multiple root pages with multiple domains, domain records for all domains must be placed to proper root pages. "All" means that you must have really all domains, which you use to access the site (including "www" and non-"www" versions if necessary).
  • You may not use shortcut of type "Random subpage" with RealURL. If you do, RealURL behaviour is undefined.

Configuration

Installation

To install the extension you can either download it from TER (the latest official version) using the TYPO3 Backend, or you can clone it from the GitHub repository. Note that installing through the Extension Manager is the preferred way. GitHub versions are “bleeding edge” and can be unstable.

Install the extension

This is documented very well in the usual TYPO3 docs: just click the little gray sphere with the plus-sign.

After the installation RealURL will prompt you to set some options and update the database. It is safe (and recommended!) to leave all options to their default values. The database must be updated for correct work of RealURL.

By default the extension is disabled and will not encode URLs. It will still decode URLs but the encoding must be enabled with the following TypoScript setup option (see below).

Configure Apache

RealURLs work by providing 'virtual paths' to 'virtual files'. These don't actually exist on the file-system, so you must tell Apache to let a PHP-script handle the request if it can't find the file. This way, all URLs to pages (like http: //www.server.com/products/product1/left.html) will be 'redirected' to /index.php, which will handle the translation of the URL into GET parameters. Real files (like images, the TYPO3 backend, static html-files, etc.) will still be handled by Apache itself though.

You should put the sample .htaccess file (called _.htaccess), which is supplied with the TYPO3 Core, in the root of your TYPO3 installation. It also contains information on which lines in that file need to be adjusted, if TYPO3 is not installed in the webroot directly, but in a subdirectory.

Alternatively, you could include the following lines in your httpd.conf, probably in the VirtualHost section. See the supplied _.htaccess file for further instructions!

Notice: For this to work you need the Apache module "mod_rewrite" and AllowOverride=All in the Directory directive.

Performance improvement for Apache redirection

If you follow the above example to configure your Apache rewrite rules, there is an unwelcome side effect: Everything is redirected to index.php (except for existing files, folders and symlinks). Now let's suppose you add a reference (by mistake) to a non-existing file, say "/fileadmin/mistake.css", this file is not found and therefor redirected to index.php. Now you've got a css style filled with some webpage content, effectively bringing your webbrowser to it's knees.

So let's do the redirecting just a bit smarter. In the following example only .html files and directories that do not exist are redirected to index.php, other non-existent files will give a 404 not found page!

 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteCond %{REQUEST_FILENAME} !-l
 RewriteRule (\.html|/)$ /index.php

TypoScript configuration

You need to activate the generation of the virtual file/path names in the TypoScript setup record, otherwise your website will not utilize the new URL encoding method.

However that is trivial; just place these four lines in the main TypoScript template record of your website:

 config.tx_realurl_enable = 1
 config.absRefPrefix = http://www.my-domain.com/
 # dont forget to set the allowed range, here 0-3; otherwise anything else could be inserted
 config.linkVars = L(0-3)

Line 1 enables the encoding of URLs as the virtual paths, the "Speaking URLs".

Line 2 makes sure all links are output as absolute links including the domain prefixed. This is required because relative references to images, stylesheets etc. will break when the virtual paths are used unless this has been set. Please see below for a detailed discussion of why this is needed. (Note: You need to enter the complete base URL, e.g. baseURL = http://www.website.tld/. You can neither leave out the http://, nor the slash at the end.)

Line 4 adds the L parameter to every link in TYPO3

config.baseURL

There is a simple solution in HTML: just supply the <base>-tag in the <head> of your pages, like:

<base href="http: //your.domain.com/">

To make your installation work correctly with RealURL, you can therefore add a base tag in your HTML templates and - more important - include this statement in your TypoScript:

config.baseURL = http://your.domain.com/

The <base> tag method wors flawlessly in TYPO3 except in cases where you have a link like <a href="#anchor_point"....> - this will not work because it refers to the site root but obviously is an 'internal' reference in the current document.

Using config.absRefPrefix among other things prevents this problem.

config.absRefPrefix

config.absRefPrefix is a TypoScript setup directive to set an absolute prefix to all links and images. Using this setting is the recommended way of making links work correctly with RealURL.

 config.absRefPrefix = http://your.domain.com/

This way TYPO3 will prefix all links with your domain making sure that not only relative or absolute, but that really full URLs are created.

Make sure you include this configuration in ALL page types that are generated!

absRefPrefix example with multiple domains

Here is an example TypoScript for two different domains

 config.absRefPrefix = localhost.tld/
 [globalString = ENV:HTTP_HOST=sub1.localhost.tld]
 config.absRefPrefix = sub1.localhost.tld/
 [global]
 [globalString = ENV:HTTP_HOST=sub2.localhost.tld]
 config.absRefPrefix = sub2.localhost.tld/
 [global]

Configuring root pages for RealURL in TYPO3

Realurl URL needs to know where the root page of the site is. It is possible to let realurl know this in three different ways:

  • By setting "Use as Root Page" in the page properties. This is enough if you have just one domain the installation.
  • By setting domain records on root pages. Not that there should be all possible domains. For example, if you add example.com and forget another.example.com, then another.example.com will not be known to realurl. Make sure that you configure domain records correctly: there should be only domain name in the Domain: field of the domain record: www.example.com is right, http://www.example.com/cms/ is wrong!
  • By specifying rootpage_id in the pagePath section of the configuration. Please, see the above configuration reference for more information on rootpage_id.

Configure the extension

Finally, you probably want to configure the way URLs are encoded. For simple needs, you can use automatic configuration. In this case, you do not have to write any configuration yourself.

For more advanced URLs, configuration will be needed. Configuration is done in "realurl_conf.php" with the variable $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl'].

Please see the section later dealing with configuration options. It also offers a lot of examples.

URL en/decoding background

This section provides a bit of background information about how URLs are encoded and decoded in the system.

The general principle is that the encoding and decoding should be totally transparent to the system. This means that any extension will work with RealURL as long as it uses the general link generation functions inside TYPO3 as it should do.

The implementation of this transparency is done by encoding the virtual URL strictly on the basis of the GET parameters given to the encoder method. And when a HTTP request is made to a virtual URL, it is decoded into a set of GET parameters which is written back to the global variables HTTP_GET_VARS / _GET - and thus any application in the system will see the parameters as if they had been passed as true GET parameters.

Encoding:

URL with GET parameters -> Speaking URL -> HTML page

Decoding:

HTTP request with Speaking URL -> URL is decoded, overriding values in HTTP_GET_VARS -> page rendered as always

The syntax of a "Speaking URL"

Before we go on to the configuration section, it is important to understand how the virtual path (Speaking URL) is decoded by the system. Let's settle an example and break it up into pieces:

index.php?id=123&type=1&L=1&tx_mininews[mode]=1&tx_mininews[showUid]=456

This URL requests page id 123 with language "1" (danish) and type "98" (probably a printable version of the page) and on that page the display of a mininews item with id "456" is requested while the "mode" of the mininews menu is "1" (which for mininews means "list"). This parameter based URL could e.g. be translated into this Speaking URL:

dk/123/news/list/456/page.html

The configuration of RealURL in 'realurl_conf.php' needed to do this magic is as follows:

PHP script:
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl']['_DEFAULT'] = array(
    'preVars' => array(
        array(
            'GETvar' => 'L',
            'valueMap' => array(
                'dk' => '1',
            ),
            'noMatch' => 'bypass',
        ),
    ),
    'fileName' => array (
        'index' => array(
            'page.html' => array(
                'keyValues' => array (
                    'type' => 98,
                )
            ),
            '_DEFAULT' => array(
                'keyValues' => array(
                )
            ),
        ),
    ),
    'postVarSets' => array(
        '_DEFAULT' => array (
            'news' => array(
                array(
                    'GETvar' => 'tx_mininews[mode]',
                    'valueMap' => array(
                        'list' => 1,
                        'details' => 2,
                    )
                ),
                array(
                    'GETvar' => 'tx_mininews[showUid]',
                ),
            ),
        ),
    ),
);

In order to understand how this configuration can translate a speaking URL back to GET parameters we have to first look at how the Speaking URLs are divided into sections. This is the general syntax:

	[TYPO3_SITE_URL] [preVars] [pagePath] [fixedPostVars] [postVarSets] [fileName]

Each of these sections (except [fileName]) can consist of one or more segments divided by "/". Thus "news/list/456/" is a sequence of three segments, namely "news", "list" and "456"

Taking the speaking URL from above (http: //www.my-domain.dk/frontend/dk/123/news/list/456/page.html) as an example we can now break it up into these sections:

Section Part from Example URL General description Comment accord. to config
[TYPO3_SITE_URL] http: //www.my-domain.dk/frontend/ This part of the URL - the base URL of the site and basically where the "index.php" script of the frontend is located - is stripped off and is of no interest to the resolving of the parameters.
[preVars] dk/ This section can contain from zero to any number of segments divided by "/". Each segment is bound to a GET-var by configuration in the key "preVars" (see example above)

The number of segments in the pre-vars section is determined exactly by the arrays in "preVars" configuration. Typical usage would be to bind a pre-var to the "L" GET parameter so the language of the site is represented by the first segment of the virtual path.

In the configuration above there is only one pre-var configured and that is bound to the GET var "L". Further a mapping table tells that the value "dk" should be translated to a "1" for the GET var value when decoded. Also, if the segment does not match "dk/" it is just ignored, meaning that the default language version of the danish page ".../dk/123/" would be just ".../123/"
[pagePath] 123/ The page path determining the page ID of the page. The default method is to just show the page ID, but through configuration you can translate e.g. the page titles, say "contact/company_info/", into a page ID. The number of segments of the path used to resolve the page ID depends on the method used. In this example the default method is used (not configured at all) and that means the raw page name (or alias if there were any) is displayed: 123.
[fixedPostVars] Fixed post vars is a sequence of fixed bindings between GET-vars and path segments, just as the pre-vars are. This is normally not useful to configure for a whole site since general parameters to pass around should probably be set as pre-vars, but you can configure fixed post vars for a single page where some application runs and in that case fixedPostVars may come in handy. Typical usage is to apply this for a single page ID running a specific application in the system. Not used in this example.
[postVarSets] news/list/456/ postVarSets are sequences of GET-var bindings (in pre-var style) initiated by the first segment of the path being an identification keyword for the sequence.

Decoding of postVarSets will continue until all remaining segments of the virtual path have been translated. This method can be used to effectively encode groups of GET vars (sets), typically for various plugins used on the website. Typical usage is to configure postVarSets for each plugin on the website.

In this example there is a single post var set ("news/list/456/") where the keyword "news/" (first segment) identifies the following sequence ("list/456/") to be mapped to the GET vars tx_mininews[mode] and tx_mininews[showUid] respectively.
[fileName] page.html The filename is always identified as the segment of the virtual path after the last slash ("/"). In the "fileName" configuration a filename can be mapped to a number of GET vars that will be set if the filename matches the index key in the array. Typical usage is to use the filename to encode the "type" or "print" GET vars of a site. In this example the "type" value "1" is mapped to the virtual filename "page.html". In any other case the type value will be set to blank.

Configuration directives

Configuration of RealURL is done in the array $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl'] which again contains arrays. The configuration directives are broken down into these tables describing options as they are grouped together in arrays within the configuration array.

To support your understanding of the options please read the background information presented previously in this document and look at the examples available.

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl']

Key Type Description
[host-name] ->siteCfg or pointer to other key with ->siteCfg in same array Configuration of Speaking URL coding based on current host-name for the website. Offers you the possibility of individual configuration for multiple domains in the same database.

If the value of an entry is a string, then the system will expect it to point to another key in on the same level and look for ->siteCfg there. Hostname is found by GeneralUtility::getIndpEnv('TYPO3_HOST_ONLY') and always in lowercase.

_DEFAULT ->siteCfg or pointer to other key with ->siteCfg in same array Default configuration, used if no matches were found for the specific HOST name.
Example
PHP script:
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['realurl'] = array(
    '_DEFAULT' => array(
        'pagePath' => array(
            'rootpage_id' => 437
        ),
        //...
    ),
    'www.typo3.org' => array (
        'pagePath' => array(
            'rootpage_id' => 111
        ),
        //...
    ),
    'www.typo3.com' => 'www.typo3.org',
    'typo3.com' => 'www.typo3.org',
    '192.168.1.123' => '_DEFAULT',
    'localhost' => '_DEFAULT',
);

In this example the keys "_DEFAULT" and "www.typo3.org" are assumed to contain proper configuration of RealURL. If the requested hostname turns out to be "www.typo3.com" or "typo3.com", the configuration of "www.typo3.org" is used. If the hostname is "192.168.1.123" or "localhost", then the "_DEFAULT" configuration is used (the two entries for "192.168.1.123" and for "localhost" are redundant since in the absence of a specific configuration, the default would be used for them anyways).

Notice how the "rootpage_id" is set differently for the two different cases! For more information on this property, see ->pagePath below.

->siteCfg

Key Type Description
cache ->cache The cache section controls the behavior of RealURL related to the cache.
init ->init General configuration of the extension
preVars [0..x] ->partDef Configuration of pre-variables; a fixed set of variables bound to the initial segments of the virtual path. See description in previous section of this document.
pagePath ->pagePath Configuration of the id-to-path transformation method. See description in previous section of this document.
fixedPostVars [pageIndex] [0..x] ->partDef Configuration of a fixed post-variable set which does not need a keyword to trigger its interpretation. Basically like pre-vars, just set after the pagePath.

See description in previous section of this document. Notice: "pageIndex" allows you to specify this for individual pages or all using "_DEFAULT" keyword. See notice below this table.

postVarSets [pageIndex] [keyword] ->postVarSet Configuration of sets of post-variables; sets of post-variables are triggered by a keyword in the virtual path.

See description in previous section of this document. Notice: "pageIndex" allows you to specify this for individual pages or all using "_DEFAULT" keyword. See notice below this table. Important: The order in which the postVarSets occur is of great importance since the first keyword definition that contains a definition for a single available GET-var will be chosen. You should arrange the postVarSets strategically.

fileName ->fileName Configuration of filename significance; filenames can be bound to specific values of GET parameters. See description in previous section of this document.

Notice: In the table above there is defined an array key, "pageIndex", for "fixedPostVars and postVarSets. This works mostly in the same way as the host-name pointer did for the outer level. The key can be

  1. either a page id, eg. "123"
  2. or the keyword "_DEFAULT".

The value of a key should be an array (according to the definition above), but if it is a string, it is interpreted as a pointer to another key on the same level.

A pointer cannot be set for "_DEFAULT". Further, only page ids can be used (internally page aliases given as parameters will be resolved first!).

Example structure
PHP script:
array(
    'init' => array(
        ...
    ),
    'preVars' => array(
        array(
            ...
        ),
        array(
            ...
        ),
    ),
    'pagePath' => array(
        ...
    ),
    'fixedPostVars' => array(
        '1383' => array (
            array(
                ...
            ),
            array(
                ...
            ),
        ),
        '123' => '1383'
    ),
    'postVarSets' => array(
        '_DEFAULT' => array (
            'consultancy' => array(
                ...
            ),
            'admin' => array(
                ...
            )
        ),
    ),
    'fileName' => array(
        ...
    )
);

This skeleton will help you to understand the structure defined in the table above for the "->siteCfg" level in the configuration.

->cache

The cache section controls the behavior of RealURL related to the cache.

Key Type Description
banUrlsRegExp string tx_indexed_search|(?:^|\?|&)q=/

This option defines a regular expressions for URLs that should not be cached. Typically those are URLs with unpredictable, free form search strings, like ones from EXT:solr or EXT:indexed_search. The default expression bans URLs from those search engines from polluting the cache.

Note that there is no check for validity of the expression. If the expression is invalid, the cache will behave unpredictably.

disable boolean Disabled RealURL cache. This should never be set to true in production because of performance reasons.

->init

General configuration of the RealURL extension.

Key Type Description
appendMissingSlash boolean / string If set, a trailing slash will be added internally to the path if it was not set by the user. For instance someone writes "http: //the.site.url/contact" with no slash at the end. "contact" will be interpreted as the filename by RealURL - and the user wanted it to be the directory. So this option fixes that problem. Note that usually such redirection is handled by the Apache web server, so just setting this to true does not make much sense.

Keyword: "ifNotFile" You can specify the option as the keyword "ifNotFile". If you use that string as value the slash gets prepended only if the last part of the path doesn't look like a filename (based on the existence of a dot "." character).

Keyword: "redirect" This keyword will force RealURL to redirect to the location with appended slash. This will ensure that pages do not appear doubled in the Google index (and therefore page rank does not suffer). The keyword can be optionally followed by the HTTP status code to use for redirect in the square brackets (for example, “redirect[301]”). The following codes are allowed: 301, 302, 303, 307. Redirect will be processed after “ifNotFile”.

emptySegmentValue type: string default: empty

If the segment is empty when encoding, use this value. This may prevent empty segments from appearing in the URL (path/to////page). Note that generally empty segments is a sign of a bad configuration.

When empty segments appear in the URL, decoding can be complicated and may fail unless the URL is in the cache.

emptyUrlReturnValue string If the URL is empty it usually is meant to be a link to the frontpage.

If you set this value to a string, that string will be the URL returned if the URL is otherwise empty. Default: "/".

postVarSet_failureMode string (keyword) When the postVarSet is not found fo the URL segment, this option defines how to handle it. Possible solutions are defined by one of the keywords listed below.

Keyword: "redirect_goodUpperDir": With this keyword RealURL will stop processing URL segments and will immediately redirect the request to a good processed part of the path.

Keyword: "ignore": With this keyword RealURL will just stop processing URL segments. Potentially this mode is not good for SEO because it can create duplicate content issues.

empty value: Empty value (default) will cause the 404 page with the message that looks like Segment "test" was not a keyword for a postVarSet as expected on page with id=12345. Usually this is the best solution because produces the expected result for the URL that does not exist.

reapplyAbsRefPrefix boolean Default: false

If config.absRefPrefix is set in TypoScript setup, RealURL will strip this prefix before making the final URL. Use this option to reapply the prefix. By default it is not set, so prefix will be lost by default. If you use linking across domains, do not put full domain name in config.absRefPrefix. Use only "/" as prefix.

->partDef

Definition of mapping between a segment of the virtual path and a GET variable or otherwise.

Key Type Description
GETvar The GET var name for which this processing is done.

Required

The value of the GETvar will pass through a transformation defined by the other configuration options here. Basically this is the flow:

  • First, check if "cond['prevValueInList']" allows processing and if not, return accordingly.
  • The value is translated through the "valueMap" if entries matches
  • If no entries in "valueMap" matched, "noMatch" is consulted for an action on this situation.
  • If noMatch did not trigger, we look for a lookup table and if defined we make a look up translation ("lookUpTable").
  • If no lookup table was defined to translate the value, we look for the "valueDefault" and if set, apply that value.
  • If none of these actions captured the value we just pass it through in its raw form.
cond['prevValueInList'] list of values If this key is set, the segment will be processed only if the previous value is found in the comma list of this value! Otherwise it will be bypassed.
valueMap array of "segment" => "Get var value" (translation table) The valueMap is a static translation table where each key represents a segment from the speaking URL and the value for the key is the true value of that parameter.

When URLs are encoded this table is reversed and if there are duplicate values the last entry is used as speaking URL value.

noMatch string keyword Keyword that defines the action if the value did not match any entry in the valueMap array.
  • "bypass" : means that if the path segment did NOT match an entry in "valueMap" the segment will be re-applied to the stack and we return/break (and thus preserves the parameter for the next segment)
  • "null" : means that if the value is NOT found in the valuemap the getParameter is not set at all.
lookUpTable ->lookUpTable Configuration of a database table by which to perform translation from id to alias string.
valueDefault string Default value to set if the path segment did not match any entries in "valueMap" or was otherwise captured for translation.

Notice: Default values are applied AFTER any "noMatch" settings are processed (and others, see flow description for key "GETvar"). RealURL will try to look in the valueMap for this value when decoding. If the value is not found, it will set it as is.

Example "preVars"
PHP script:
    'preVars' => array(
        array(
            'GETvar' => 'no_cache',
            'valueMap' => array(
                'no_cache' => 1,
            ),
            'noMatch' => 'bypass',
        ),
        array(
            'GETvar' => 'L',
            'valueMap' => array(
                'dk' => '1',
                'danish' => '1',
                'uk' => '2',
                'english' => '2',
            ),
            'noMatch' => 'bypass',
        ),
    ),

The above example shows a configuration that allows two preVars in a path, BUT they are both optional (due to the "noMatch" => "bypass" setting).

Normally a URL in the default language would look like this:

123/page.html

Then, if the L=1 GETvar is set, the URL will be like this:

danish/123/print.html

Finally, if the first segment matches "no_cache" the "no_cache=1" GET var is set and the interpretation of the language GETvar is moved to segment 2:

no_cache/danish/123/print.html

The concept of bypassing non-matched values opens the possibility of errors, if two values from neighbouring configurations match. For instance errors would result from having a language labeled "no_cache" since that also is a keyword in the configuration of the first segment!

Removing the "noMatch" setting will yield these URLs instead:

//123/page.html
/danish/123/page.html
no_cache/danish/123/print.html

A better solution would be to set a default value for the language:

PHP script:
    'preVars' => array(
        array(
            'GETvar' => 'no_cache',
            'valueMap' => array(
                'no_cache' => 1,
            ),
            'noMatch' => 'bypass',
        ),
        array(
            'GETvar' => 'L',
            'valueMap' => array(
                'dk' => '1',
                'danish' => '1',
                'uk' => '2',
                'english' => '2',
            ),
            'valueDefault' => 'uk',
        ),
    ),

This would yield this result:

uk/123/page.html
danish/123/page.html
no_cache/danish/123/print.html

It still maintains the bypass-setting for the "no_cache" parameter but that might just fit in nicely.

Example "fixedPostVars"
PHP script:
    'fixedPostVars' => array(
        'testPlaceHolder' => array (
            array(
                'GETvar' => 'tx_extrepmgm_pi1[mode]',
                'valueMap' => array (
                    'new' => 1,
                    'categories' => 2,
                    'popular' => 3,
                    'reviewed' => 4,
                    'state' => 7,
                    'list' => 5,
                )
            ),
            array(
                'cond' => array(
                    'prevValueInList' => '2'
                 ),
                'GETvar' => 'tx_extrepmgm_pi1[display_cat]',
                'valueMap' => array (
                    'docs' => 10,
                ),
            ),
            array(
                'GETvar' => 'tx_extrepmgm_pi1[showUid]',
                'lookUpTable' => array(
                            'table' => 'tx_extrep_keytable',
                            'id_field' => 'uid',
                            'alias_field' => 'extension_key',
                            'addWhereClause' => ' AND NOT deleted'
                        )
            ),
            array(
                'GETvar' => 'tx_extrepmgm_pi1[cmd]',
            )
        ),
        '1383' => 'testPlaceHolder',
    ),

This configuration shows how "fixedPostVars" can be used like "preVars" but after the page path. Typically it would be used on a single page where a known plugin runs. In the above example this is the case; page id "1383" is pointed to the configuration "alias" named "testPlaceHolder". The example is designed for the typo3.org Extension Repository.

The configuration sets up a sequence of 3-4 segments in the virtual path. The first is the main menu where integer values defining the mode is mapped to nice alias strings. The second segment is the category id to display but notice how the cond["prevValueInList"] is set to "2" - this means that only if the previous variable was "2" then will this segment be interpreted, otherwise bypassed! Finally there is the extension uid, here configured for translation to/from the extension keys. That is a safe process since the extension keys are unique. Finally the "command" which defines the menu level when displaying single extensions.

This configuration allows for a URL like this (4 segments in "fixedPostVars" sequence):

http: //typo3.org/1383/categories/docs/coding_guidelines/details/

or (only 3 segments in "fixedPostVars" sequence, since first segment was not "categories" / 2)

http: //typo3.org/1383/popular/skin1/details/

->lookUpTable

Defines a table to use for look up in translation of id to alias strings for GETvars.

Key Type Description
table string Table name
id_field string Fieldname of the field holding the id, typically an integer, eg. "uid"
alias_field string Fieldname of the field holding the alias string matched to the id. Should be unique.
addWhereClause string Additional where clause to add to the look up query. Has to be set automatically, even for "deleted" fields since the lookup might take place before any table configuration is accessible!

Example value is: "AND NOT deleted"

maxLength integer Defines the maximum accepted length of the alias value. If the alias value is longer than this integer the original value will be returned instead.

Default value is "100"

useUniqueCache boolean If set, the translation from id to alias is automatically stored in a look-up table where the uniqueness of the alias is ensured; When storing it is simply checked if the alias is already associated with another ID (in the same table/fields combination) and if so a unique alias is created, typically the requested alias with numbers appended.
useUniqueCache_conf['strtolower'] boolean If set, the aliases are converted strtolower()
useUniqueCache_conf['spaceCharacter'] string Normally, this defaults to an underscore (_), which is used to replace spaces and such in an URL. You can set this to e.g. a hyphen (-) if you want to.
useUniqueCache_conf['encodeTitle_userProc'] user function Additional user processing for alias cleanup.
languageField is an options field that defines what field in th table contains language id of the record. Typically it is sys_language_uid. Same as [ctrl][languageField] in $TCA
transOrigPointerField is the same as [ctrl][transOrigPointerField] in $TCA for the table
languageExceptionUids defines languages where translation will not be used (you may want to use language title for asian languages, for example)
enable404forInvalidAlias will produce a 404 page in case if the alias cannot be resolved
Example
PHP script:
'lookUpTable' => array(
	'table' => 'user_3dsplmxml_bfsbrand',
	'id_field' => 'xml_id',
	'alias_field' => 'xml_title',
	'maxLength' => 10,
	'addWhereClause' => ' AND NOT deleted'
)
Example: Language prefix
PHP script:
    'preVars' => array (
        array(
            'GETvar' => 'L',
            'valueMap' => array(
                'dk' => '1',
            ),
            'noMatch' => 'bypass',
        ),
    ),

In this example a language prefix is configured.

The result of this configuration should be clear from looking at the examples in the following table:

URL What happens
http: //typo3.org/1420/ Shows page 1420
http: //typo3.org/dk/1420/ Shows page 1420 in danish (&L=1)

->pagePath

Configuration of the method that en/decodes the id to/from a "page path"

Key Type Description
rootpage_id integer Default: empty

This option is strongly recommended to be set in all cases. While RealURL is often able to discover root page id correctly from domain records, it is better to set this value manually in the configuration.

expireDays integer The time the old URL of a page whose pagetitle changed will still be remembered (in days)
spaceCharacter string This defaults to hyphen (-), which is used to replace spaces and such in a URL. You can set this to e.g. an underscore (_) if you want to.

This setting is deprecated.

Example of page id translation to path:
PHP script:
    'pagePath' => array(
        'spaceCharacter' => '_',
        'expireDays' => 3
    ),

Renders a true Speaking URL of the page titles.

By the configuration above URLs will look like this (before / after):

1420/index.html
extensions/index.html
 
1420/repository/popular/skin1/details/index.html
extensions/repository/popular/skin1/details/index.html
 
1440/index.html
documentation/glossary/index.html
 
1409/index.html
about/license/gpl_for_developers/index.html
 
1342/showreference/52/
about/yet_another_typo3_site/showreference/52/

->postVarSet

Key Type Description
type string keyword By default a postVarSet consists of
  • a keyword that identifies the following sequence in the virtual path
  • a sequence of one or more segments in the path which is mapped to GETvars

An example (from previously) is "news/list/456/" where the keyword "news/" (first segment) identifies the following sequence ("list/456/") to be mapped to the GET-vars tx_mininews[mode] and tx_mininews[showUid] respectively (according to configuration). The configuration of the sequence is done by a numeric array of ->partDef. Other modes: There are other modes than the default mode and they can be triggered by setting the "type" key to one of the following keywords. In these alternative cases there might not be any sequence of segments after the keyword, but still the keyword is triggering the alternative mode so that will always be around. "single" : Using this keyword you bind the keyword to represent an exact amount of GETvars with exact values. This works precisely like filenames are bound to GETvars (see ->fileName)

Only default type:
[0..x] ->partDef The configuration of the sequence associated with the "keyword" that defines this postVarSet.
Only "single" type:
keyValues array of [GETvar] => [string value] The "keyValues" array defines one or more GET variables with specific values. The keyword of the postVarSet is matched if if all the GET-vars configured in ["keyValues"] is found in the remaining pool of GET vars that needs translations and if the values match exactly!
Example: PostVarSets
PHP script:
    'postVarSets' => array(
        '_DEFAULT' => array (
            'plaintext' => array(
                'type' => 'single',    // Special feature of postVars
                'keyValues' => array (
                    'type' => 99
                )
            ),
            'ext' => array(
                array(
                    'GETvar' => 'tx_myExt[p1]',
                ),
                array(
                    'GETvar' => 'tx_myExt[p2]',
                ),
                array(
                    'GETvar' => 'tx_myExt[p3]',
                ),
            ),
            'news' => array(
                array(
                    'GETvar' => 'tx_mininews[mode]',
                    'valueMap' => array(
                        'list' => 1,
                        'details' => 2,
                    )
                ),
                array(
                    'GETvar' => 'tx_mininews[showUid]',
                ),
            ),
        ),
    ),

This example shows how three sets of postVarSets have been configured of which two of them are the default type (keyword + sequence of GETvars) while the third is of the "single" type, mapping to a fixed GETvar value.

In order to understand this configuration and the effect it has you should study these commented examples based on the above configuration. Each example consists of two lines where the first is the URL with GETparameters and the second is the Speaking URL version of the first.

index.php?id=123&tx_myExt[p3]=ccc&tx_myExt[p2]=bbb&tx_myExt[p1]=aaa
123/ext/aaa/bbb/ccc/

Above, the postVarSet "ext" is used to encode the GET parameters. The sequence is initiated by the keyword "ext" and the following three segments of the virtual path is mapped to the three GET-vars configured for the keyword and in the order they appear in the configuration above (line 10-18)

index.php?id=123&tx_myExt[p1]=aaa
123/ext/aaa/
index.php?id=123&tx_myExt[p1]=aaa&tx_myExt[p2]=bbb
123/ext/aaa/bbb/

The above two examples shows what happens if only one or two of the parameters are used - basically the empty values are stripped off from the end of the path. The first example would actually render "123/ext/aaa///" and the second would be "123/ext/aaa/bbb//" but since the empty values are in the end of the path we can safely strip them off as the example shows.

index.php?id=123&tx_myExt[p1]=aaa&tx_myExt[p3]=ccc
123/ext/aaa//ccc/

In this example only "tx_myExt[p1]" and "tx_myExt[p3]" is used and since the sequence requires "p2" to be in between we have to accept the empty segment of the virtual path.

index.php?id=123&tx_mininews[showUid]=123&tx_mininews[mode]=1
123/news/list/123/

In the above example the mininews parameters are encoded, using the keyword "news". Notice that the "tx_mininews[mode]" GETvar has a mapping table which allows automated translation between the value "1" and "list" used in the virtual URL. This feature (and other similar options) allows to create truely speaking URLs even for parameters that are ID numbers.

index.php?id=123&tx_mininews[showUid]=123&tx_mininews[mode]=1&tx_myExt[p1]=aaa&tx_myExt[p2]=bbb&tx_myExt[p3]=ccc
123/ext/aaa/bbb/ccc/news/list/123/

In this example we have two postVarSets, namely "ext" and "news". As you can see this is no problem at all as long as the sequences contains the correct amount of segments so the next keyword gets registered.

Notice that the "ext" keyword gets listed first. This is because the "ext" postVarSet is the first one found in the configuration and therefore is triggered before the "news" postVarSet.

index.php?id=123&tx_mininews[showUid]=123&tx_myExt[p1]=aaa&tx_myExt[p3]=ccc
123/ext/aaa//ccc/news//123/

In this example we have left out two parameters from the previous URL and that means there are two empty segments in the virtual path. There is no way around this since the sequence length has to be respected and in case of the "news" postVarSet the "mode" was defined before the "showUid" parameter which means it is not possible to strip of the the empty value.

index.php?id=123&type=99&tx_myExt[p1]=aaa&unknownGetVar=foo
123/plaintext/ext/aaa/?unknownGetVar=foo

This example is only different to the above examples by showing what happens to an unknown GET var when a URL is encoded; quite simply that GET var is appended to the final URL - what else!

->fileName

The fileName section defines how RealURL treats the last segment of the URL. It is possible to make the URL look like /path/to/news/item/ or /path/to/news/item.html or have something like rss.xml in the end and to decode it to a certain page type.

Key Type Description
index[filename]["keyValues"] array of [GETvar] => [string value] The "index" is an array of virtual filenames (eg. "page.html") which is associated with one or more GET variables with specific values.

A filename is chosen during encoding if all the GET-vars configured in index[filename]["keyValues"] is found in the remaining pool of GET vars that needs translations and if the values match exactly! The filename value "_DEFAULT" is used if no match was found. Important: The order in which the filenames occur is of great importance since the first filename that matches will be chosen. You should arrange the filenames strategically. See example below.

acceptHTMLsuffix boolean/string Default: true

If set to boolean, defines whether RealURL will treat URLs ending to / or .html identically. It can also be set to a string to limit the suffix to a certain value. The value must include a dot (example: .html)

defaultToHTMLsuffixOnPrev boolean Default: false

Identical to acceptHTMLsuffix for decoding (and overrides it) but also used for encoding of URLs. Same format as acceptHTMLsuffix. For example, "workplace-learning-solutions/companion-solutions/" would be turned into "workplace-learning-solutions/companion-solutions.html" and the basepart of the filename (stripping the ".html" extension) will still be perceived as the last part of the virtual path. This approach is useful if you want to simulate HTML documents even if you don't configure any fileName mappings.

Example: Print page
PHP script:
    'fileName' => array (
        'index' => array(
            'print.html' => array(
                'keyValues' => array (
                    'type' => 98,
                )
            ),
        ),
    ),

This configures a print version based on the output of typeNum 98. When there should be no "type" value the default key is used (which renders no filename of course) but if the &type value is 98, "print.html" is used; this filename will then represent the GET var "&type=98" during decoding.

Example: Default filename
PHP script:
    'fileName' => array (
        'index' => array(
            'index.html' => array(
                'keyValues' => array(
                )
            ),
        ),
    ),

This example shows a configuration that will prefix the filename "index.html" by default no matter what.

_DOMAINS

_DOMAINS configuration allows you to set domain name for the links according to a value of the $_GET parameter. Most often it happens for languages. See this blog post for the description of the feature.