[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 of and is of no interest to the resolve 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 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 id (or alias if there were any) is displayed; 123.

This is not “Speaking URL” behaviour, sorry for this weak example...

[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 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 has 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.

[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 t3lib_div::getIndpEnv('TYPO3_HOST_ONLY') and always in lowercase.

_DEFAULT

->siteCfg or pointer to other key with ->siteCfg in same array

Configuration of default Speaking URL coding if no matches was found for the specific HOST name.

init

->init

General configuration of the extension

redirects [path]

Redirect URL

Here you can specify virtual paths that should not be processed into GET vars but rather trigger a HTTP redirect header directly to the URL entered as value. If such a match happens the script issues a location-header and exits.

redirects_regex[regex]

Redirect URL

Extended version of the [redirects] configuration above where you can match the path with a regex. You can also use back-references in the redirect URL.

Example:

'redirects_regex' => array(

    '^downloads/(.*)' => 'ftp://dl.domain.tld/public/dl/\1',

),

With this configuration any URL starting with the path “downloads/” will be redirected to the ftp-server. For instance, “http://www.domain.tld/downloads/software/game.exe” will be redirected to “ftp://dl.domain.tld/public/dl/software/game.exe”

'^francais/(.*)' => 'fr/\1',

This example will redirect any URL starting with “francais/” to “fr/” which is supposedly the right key of the language on the site

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.

doNotRawUrlEncodeParameterNames

boolean

Disable rawurlencoding of non-translated GET parameter names during encoding.

Background:

During the encoding of Speaking URLs from GET parameters any GET parameters that cannot be translated into a Speaking URL will be set as GET parameters again. During this process the parameter name will be rawurlencoded as it actually should according to the RFCs covering this topic.

This means that a parameter like “tx_myext[hello]=world” will become “tx_myext%5Bhello%5D=world“ instead - which is not as nice visually but more correct technically.

enableCHashCache

boolean

If set, “cHash” GET parameters are stored in a cache table if they are the only parameters left as GET vars. This allows you to get rid of those remaining parameters that some plugins might use to enable caching of their parameter based content.

respectSimulateStaticURLs

boolean

If set, all requests where the Speaking URL path is only a single document with no path prefix (eg. “123.1.html”) are ignored as Speaking URLs. This flag can enable backwards compatibility with old URLs using simulateStaticDocuments on the site.

This flag is ignored if the following conditions are all met:

appendMissingSlash

boolean / string

If set, the 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 in 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.

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).

adminJumpToBackend

boolean

If set, then the "admin" mode will not show edit icons in the frontend but rather direct the user to the backend, going directly to the page module for editing of the current page id.

postVarSet_failureMode

string (keyword)

Keyword: "redirect_goodUpperDir". Will compose a URL from the parts successfully mapped and redirect to that.

Keyword: "ignore": A silent accept of the remaining parts.

Default (blank value) is a 404 page not found from TYPO3s frontend API.

disableErrorLog

boolean

If true, 404 errors are not written to the log table.

enableUrlDecodeCache

boolean

If true, caching of URL decoding is enabled.

The cache table is flushed when "all cache" is flushed in TYPO3. Entries for decode cache is valid for 24 hours by default.

If you set this option with tx_reaurl_advanced in a multi domain environment, you must also set rootPageID or enableDomainLookup. Without one of those two options, enableUrlDecodeCache may cause wrong path‑to‑id resolving.

enableUrlEncodeCache

boolean

If true, caching of URL encoding is enabled.

The cache table is flushed when "all cache" is flushed in TYPO3.

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 will be the URL returned if the URL is otherwise empty.

If you set this value true (PHP boolean, “TRUE”), then it will return the baseURL set in TSFE.

Setting it to “./” should work as a reference to the root as well. But it is not so beautiful.

type

string keyword

By default the array defines a GETvar mapping but there are alternatives which are configured by setting the type key:

“action” : If set, the segment can define various actions, like setting frontend editing or redirecting to a certain URL, setting some parameters.

type = “action”

index[segment]

index[“_DEFAULT”]

->actionConfig

(or blank value which will just accept the segment but take no action on it)

The index array defines various actions and the first segment of the path is used as key to look up which action in the array to take.

See ->actionConfig for more details and examples.

Default type

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:

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.

userFunc

userFunc

User function to do id<=>alias mapping. Only used if “lookUpTable” is not.

Example configuration:

'userFunc' => 'EXT:realurl/class.tx_realurl_userfunctest.php:&tx_realurl_userfunctest->main'

Example class in “realurl” (class.tx_realurl_userfunctest.php)

class tx_realurl_userfunctest  {

        function main($params, $ref)    {

                if ($params['decodeAlias'])     {

                        return $this->alias2id($params['value']);

                } else {

                        return $this->id2alias($params['value']);

                }

        }

        function id2alias($value)       {

                return '--'.$value.'--';

        }

        function alias2id($value)       {

                if (ereg('^--([0-9]+)--$',$value,$reg)) {

                        return $reg[1];

                }

        }

}

This class will change an id “6” to the alias “--6--” when encoded. During decode the alias “--6--” is changed back to “6”. Of course this doesn't make much sense in terms of speaking URLs but with such a user function you can encode and decode ids/aliases as you like!

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”)

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.

languageGetVar

string

Set to the GET variable name that is used to identify language uid (typically “L”). If this is set, a localized title will be looked up in case the table supports localization with “languageField” and “transOrigPointerField” set.

For the configuration you HAVE TO duplicate the field names for “languageField” and “transOrigPointerField” from $TCA of the table. This is because that during URL analysis the TCA array is not yet available to the system and thus we cannot look the values up there.

An example is this, using the “tt_news” table in the modern version. See the four bold lines for an example of the combined configuration needed to make localized urls for news entries:

'lookUpTable' => array(

        'table' => 'tt_news',

        'id_field' => 'uid',

        'alias_field' => 'title',

        'maxLength' => 50,

        'useUniqueCache' => 1,

        'addWhereClause' => ' AND NOT deleted',

        'languageGetVar' => 'L',

        'languageExceptionUids' => '',

        'languageField' => 'sys_language_uid',

        'transOrigPointerField' => 'l18n_parent'

)

languageField

string

Same as [ctrl][languageField] in TCA for the look up table.

transOrigPointerField

string

Same as [ctrl][transOrigPointerField] in TCA for the look up table.

languageExceptionUids

string

List of sys_language uids to except in case “languageGetVar” is used (see below).

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']

userFunc

Additional processing of the alias before it is cached.

enable404forInvalidAlias

boolean

If true, a 404 will be thrown if an alias being resolved wasn't found to match and id.

autoUpdate

boolean

If true, (and useUniqueCache is set) the aliases will automatically update themselves.

expireDays

integer

Number of days in which older aliases will expire if “autoUpdate” is used. Default is 60 days.

type

string keyword

The action is identified by one of these keywords:

“admin” : Enables the Frontend Editing features (similar feature to ->postVarSet, type = “admin”.

“redirect” : Redirects you to another URL with optional markers filled with the value of the path segment and the remaining path. Useful for site shortcuts

“notfound” : Throws a 404 error

“bypass” : Bypass AND adds the key to the stack again! (because the key belongs to next part of URL)

“feLogin” : Adds keyword when users are logged in. Feature that allows different URL during logins, mainly useful for cache-control headers which needs a different URL for logged in sessions in order to server non-cached pages for login users. Notice: This feature will actually check for a logged in user; groups added by IP masks or otherwise will not be recognized as a login session.

default: Passthrough(without adding key to stack).

Notice about the “_DEFAULT” key: If the “_DEFAULT” type is not “bypass” (meaning that the _DEFAULT action is to do something) the URL encoding method will look for the first occurence of an action of no type (passthrough without adding key to stack) and use that as segment value.

Only type “redirect”

url

string

The URL to redirect to. There are two markers you can use in the URL:

###INDEX### - Inserts the current segment.

###REMAIN_PATH### - Inserts the remaining path from this point (including any filename)

The values are rawurlencoded()

type

string

Setting the method used for encoding/deconding of the ID

The default simply is to set the page id/alias as a single entry in the virtual path.

“user” : Calls external class for generation.

Only  type “user”:

userFunc

function reference

Function reference to handle the id encoding.

Examples can be found in class.tx_realurl_dummy.php

An full fledged implementation is found in “class.tx_realurl_advanced.php”. See more details later in documentation about this.

Example value:

EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_advanced->main

rootpage_id

integer

Defines the root page uid of the site for which the configuration is made.

This setting is mandatory if you run multiple sites in the same database using real urls for more than one site. This setting makes possible for the “path-to-id” algorithms to distinguish the sites. For instance two sites might have the same page title on the first level that will generate the same speaking url path. In such case two different IDs are associated with the same page path and something is needed to distinguish the look ups.

In order to configure different sites you simply use the possibility to make different configuration for different domains. See the main section about configuration.

It is important that you use the uid of the root page in the sites. Otherwise the fall-back look up of page paths will not work correctly.

You do not need to set this setting if you have only one site in realurl configuration.

See example in the tx_realurl_advanced section.

[other keys can depend on user functions.]

type

string keyword

By default a postVarSet consists of

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)

“admin” : Using this keyword the backend will enable frontend editing mode for the user, showing the context sensitive edit icons in the frontend. If the user is not logged in as a backend user there will be a redirect to the backend login form where the user can login and after successful login the user will be redirected to the previous page.

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!

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.

defaultToHTMLsuffixOnPrev

boolean/string

If set, then the last directory part of the virtual path being made will be turned into the filename suffixed “.html” IF the filename part is non-existing.

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.

If set to string, that string will be used as suffix. Notice that leading dot is mandatory (i.e. valid suffix is “.html”, not just “html”)

acceptHTMLsuffix

boolean/string

If URL contains “.html” suffix and this property is enabled, then this suffix will be stripped from url. This allows you to easily migrate old site to TYPO3, keep all incoming external links working but use urls with another suffix (through defaultToHTMLsuffixOnPrevid is ) or without suffix at all.