RealURL

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

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.

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.

enableUrlDecodeCache

boolean

If true, caching of URL decoding is enabled.

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

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:

• First, check if "condPrevValue" 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")

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.

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!

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

http://typo3.org/

This URL would result in a 404 error if it wasn't for the redirect configuration in line 1-4 of the configuration. Here the system is ordered to redirect to "cms/" in case there is no virtual path found.

http://typo3.org/cms/1420/

This will show page ID 1420. The action key "cms" doesn't do anything - it just bypasses the processing to the next level which is the page ID resolving. By configuring such a prefix you basically define all of your site to "run" from the virtual directory "cms/".

Configuration is in line 9

http://typo3.org/admin/1420/

This will also show page ID 1420 but activate the frontend editing icons in the interface - and if the user is not currently logged in as a backend user a redirect to the backend login form will happen. Configuration of this feature is in line 10-12

When using the Frontend Editing trigger ("admin") in "realurl" the "admin/" segment of the path will be carried around in the links on the site so you stay in admin mode until you remove it again. But this is also means that caching is disabled for all pages so page links are never stored with the "admin/" action in!

http://typo3.org/search/system+requirements

Will redirect to http://typo3.org/index.php?id=1344&tx_indexedsearch[sword]=system%2Brequirement which is the page where the indexed_search plugin is running and automatically performing a search for the words after "search/".

This is configured in line 13-16; notice how the search word (the remaining path) is automatically inserted in the URL by the marker string "###REMAIN_PATH###"

http://typo3.org/ext/lang

Will redirect to http://typo3.org/cms/1383/list/lang/index.html where "lang" is inserted by the marker "###REMAIN_PATH###" just like with the "search" action before. The principles are the same. Configuration in line 17-20

http://typo3.org/mailinglist/

Will redirect to  http://lists.netfielders.de according to line 3 in the configuration

http://typo3.org/1420/

Shows page 1420

http://typo3.org/admin/1420/

Shows page 1420 with Frontend Editing icons

http://typo3.org/dk/1420/

Shows page 1420 in danish (&L=1)

http://typo3.org/admin/dk/1420/

Shows page 1420 in danish (&L=1) with Frontend Editing icons

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

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)

"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

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.