Realurl/manual
From TYPO3Wiki
<< Back to Extension manuals page
This is the wiki-version of the manual for RealURL: URLs like normal websites (realurl) (contact: dmitry)
Real URL
Extension Key: realurl
Copyright 2003-2004
Martin Poelstra, <martin@beryllium.net> & Kasper Skårhøj <kasper@typo3.com>
This document is published under the Open Content License
available from http: //www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
- a GNU/GPL CMS/Framework available from www.typo3.com
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.
Examples
| Typed URL | TYPO3 id and type |
|---|---|
| http: //www.domain.com/ | id=0, type=0 |
| http: //www.domain.com/products/product1/features/ | id=123, type=0 |
| http: //www.domain.com/products/product1/features/leftframe.html | id=123, type=2 |
Background
TYPO3 works with page-IDs. This works great, however the URLs are very 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 has advantages and drawbacks but the bottomline is that you might have to fix your templates/coding various places to be compatible.
- Screenshot (typo3.org extensions encoding)
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 ("tslib_cObj::typolink", "t3lib_tstemplate::linkData")
- URLs are cached, so translating between URLs and IDs is very fast.
- It can handle different frames, or other pagetypes
- URLs are multilingual: if you're browsing in Dutch, you'll see Dutch URLs
- Once configured the systems 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
Rawurlencoding of remaining parameter GEt vars names
- Disable "simulateStaticDocuments"!!
....
Configuration
Installation
To install this extension, four steps must be taken:
- Install it in the Extension Manager
- Configure Apache
- Modify your templates for Real URLs
- Configure the extension in typo3conf/localconf.php
Install the extension
This is documented very well in the usual TYPO3 docs: just click the little gray sphere with the plus-sign and when it asks for any changes to commit, let it make them. It's not doing anything yet though.
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 supplied sample .htaccess file (called _.htaccess) in the root of your TYPO3-installation.
Alternatively, you could include the following lines in your httpd.conf, probably in the VirtualHost-section. Here is an example:
<VirtualHost 127.0.0.1>
DocumentRoot /var/www/typo3/dev/testsite-3/
ServerName www.test1.intra
RewriteEngine On
RewriteRule ^/typo3$ - [L]
RewriteRule ^/typo3/.*$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* /index.php
</VirtualHost>
If you put it into a .htaccess file it has to look slightly different, basically stripping the leading slashes ("/"):
RewriteEngine On
RewriteRule ^typo3$ - [L]
RewriteRule ^typo3/.*$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* index.php
This will tell Apache that it should rewrite every URL that's not a filename, directory or symlink. It leaves everything starting with /typo3/ alone too.
Notice: For this work you need the Apache module "mod_rewrite"! and AllowOverride=All in the Directory directive
TypoScript configuration
Like with "simulateStaticDocuments" you need to activate the generation of the virtual file/path names in the TypoScript record ? otherwise your website will not utilize the new URL encoding method.
However that is trivial; just place these five lines in the main TypoScript template record of your website:
<TS> :
Line 1 simply disables "simulateStaticDocuments" - "realurl" is incompatible with simulateStaticDocuments and will simply not work if it has been enabled. This line should remind you of this fact.
Line 2 makes the frontend output a "<base>" tag in the header of the pages. 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 detail discussion of why this is needed. (Note: config.baseURL won't work anymore in 3.8.1, you need to enter a base URL, e.g. baseURL = http://www.website.tld/. Neither can you leave out the http://, nor the slash at the end. ).
Line 3 enables the encoding of URLs as the virtual paths, the "Speaking URLs".
Line 4 makes clear that, in case the &L parameter is used more than once in the URL, only the last occurence will be used
Line 5 adds the L parameter to every link in Typo3
baseURL-Example
config.baseURL = localhost.tld/ [hostname = sub1.localhost.tld] config.baseURL = sub1.localhost.tld/ [global] [hostname = sub2.localhost.tld] config.baseURL = sub2.localhost.tld/ [global]If this is not working, try: <TS> :
config.baseURL = localhost.tld/ [globalString = ENV:HTTP_HOST=sub1.localhost.tld] config.baseURL = sub1.localhost.tld/ [global] [globalString = ENV:HTTP_HOST=sub2.localhost.tld] config.baseURL = sub2.localhost.tld/ [global]
Configure the extension
Finally, you probably want to configure the way URLs are encoded. For simple needs this is quite easy and the more advanced URLs you want to encode the more configuration you need - simple isn't it.
Configuration is done in "localconf.php" with the variable $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 they use the general link generation functions inside TYPO3 as they should do already. You can also use "simulateStaticDocuments" as a test - if it worked with that, it will (most likely) work with the "realurl" extension as well.
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 it they were passed as true GET parameters.
Encoding:
URL with GET parameters -> Speaking URL -> HTML page
The encoding of the URLs happens by using a hook in the method t3lib_tstemplate::linkData(). This is configured in "realurl/ext_localconf.php": <PHP> :$TYPO3_CONF_VARS['SC_OPTIONS']['t3lib/class.t3lib_tstemplate.php']['linkData-PostProc'][] = 'EXT:realurl/class.tx_realurl.php:&tx_realurl->encodeSpURL';
Decoding:
HTTP request with Speaking URL -> URL is decoded, overriding values in HTTP_GET_VARS -> page rendered as always
The decoding of the URLs happens by using a hook in tslib_fe::checkAlternativeIdMethods(). This is configured like this: <PHP> :$TYPO3_CONF_VARS['SC_OPTIONS']['tslib/class.tslib_fe.php']['checkAlternativeIdMethods-PostProc'][] = 'EXT:realurl/class.tx_realurl.php:&tx_realurl->decodeSpURL';
The syntax of a "Speaking URL"
Before we go on to the configuration section it's important to understand how the virtual path (Speaking URL) is decoded by the system. Lets 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 "1" (probably a content frame in a frameset) and on that page the display of a mininews item with id "456" is requested while the "mode" of the mininews menu is "1" (list). This parameter based URL could be translated into this Speaking URL:
dk/123/news/list/456/page.htmlThe configuration of "realurl" in 'localconf.php' needed to do this magic is as follows: <PHP> :
1: $TYPO3_CONF_VARS['EXTCONF']['realurl']['_DEFAULT'] = array( 2: 'preVars' => array( 3: array( 4: 'GETvar' => 'L', 5: 'valueMap' => array( 6: 'dk' => '1', 7: ), 8: 'noMatch' => 'bypass', 9: ), 10: ), 11: 'fileName' => array ( 12: 'index' => array( 13: 'page.html' => array( 14: 'keyValues' => array ( 15: 'type' => 1, 16: ) 17: ), 18: '_DEFAULT' => array( 19: 'keyValues' => array( 20: ) 21: ), 22: ), 23: ), 24: 'postVarSets' => array( 25: '_DEFAULT' => array ( 26: 'news' => array( 27: array( 28: 'GETvar' => 'tx_mininews[mode]', 29: 'valueMap' => array( 30: 'list' => 1, 31: 'details' => 2, 32: ) 33: ), 34: array( 35: 'GETvar' => 'tx_mininews[showUid]', 36: ), 37: ), 38: ), 39: ), 40: );
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 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. |
Configuration directives
Configuration of "realurl" is done in the array $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.
$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 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. |
Example
<PHP> :1: $TYPO3_CONF_VARS['EXTCONF']['realurl'] = array( 2: '_DEFAULT' => array( 3: ... 4: ), 5: 'www.typo3.org' => array ( 6: ... 7: ), 8: 'www.typo3.com' => 'www.typo3.org', 9: 'typo3.com' => 'www.typo3.org', 10: '192.168.1.123' => '_DEFAULT', 11: 'localhost' => '_DEFAULT', 12: );
In this example the keys "_DEFAULT" and "www.typo3.org" is assumed to contain proper configuration of "realurl". If the 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 (which is redundant since it would be defaulted to anyways!)
->siteCfg
| Key | Type | Description |
|---|---|---|
| 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. |
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
- either a page id, eg. "123"
- 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> :1: array( 2: 'init' => array( 3: ... 4: ), 5: 'redirects' => array( 6: => 'cms/', // If default URL, redirect to subdir "cms/" 7: 'test/' => 'http: //www.test.test/', // If subdir is "test/" then redirect to URL 8: 'myFolder/mySubfolder/myFile.html' => 'test/index.php', 9: ), 10: 'preVars' => array( 11: array( 12: ... 13: ), 14: array( 15: ... 16: ), 17: ), 18: 'pagePath' => array( 19: ... 20: ), 21: 'fixedPostVars' => array( 22: '1383' => array ( 23: array( 24: ... 25: ), 26: array( 27: ... 28: ), 29: ), 30: '123' => '1383' 31: ), 32: 'postVarSets' => array( 33: '_DEFAULT' => array ( 34: 'consultancy' => array( 35: ... 36: ), 37: 'admin' => array( 38: ... 39: ) 40: ), 41: ), 42: 'fileName' => array( 43: ... 44: ) 45: );
This skeleton will help you to understand the structure defined in the table above for the "->siteCfg" level in the configuration. Notice the examples for redirects.
->init
General configuration of the "realurl" extension
| Key | Type | Description |
|---|---|---|
| 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. |
->partDef
Definition of mapping between a segment of the virtual path and a GET variable or otherwise.
| Key | Type | Description |
|---|---|---|
| type | string keyword | By default the array defines a GETvar mapping but there are alternatives which are configured by setting the type key:
|
| 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.
|
| 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") |
Example:
<PHP> :1: 'preVars' => array( 2: array( 3: 'GETvar' => 'no_cache', 4: 'valueMap' => array( 5: 'no_cache' => 1, 6: ), 7: 'noMatch' => 'bypass', 8: ), 9: array( 10: 'GETvar' => 'L', 11: 'valueMap' => array( 12: 'dk' => '1', 13: 'danish' => '1', 14: 'uk' => '2', 15: 'english' => '2', 16: ), 17: 'noMatch' => 'bypass', 18: ), 19: ),
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 error if two values from neighbouring configurations matches. For instance errors would result from having a language labeled "no_cache" since that 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> :1: 'preVars' => array( 2: array( 3: 'GETvar' => 'no_cache', 4: 'valueMap' => array( 5: 'no_cache' => 1, 6: ), 7: 'noMatch' => 'bypass', 8: ), 9: array( 10: 'GETvar' => 'L', 11: 'valueMap' => array( 12: 'dk' => '1', 13: 'danish' => '1', 14: 'uk' => '2', 15: 'english' => '2', 16: ), 17: 'valueDefault' => 'uk', 18: ), 19: ),
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"
1: 'fixedPostVars' => array( 2: 'testPlaceHolder' => array ( 3: array( 4: 'GETvar' => 'tx_extrepmgm_pi1[mode]', 5: 'valueMap' => array ( 6: 'new' => 1, 7: 'categories' => 2, 8: 'popular' => 3, 9: 'reviewed' => 4, 10: 'state' => 7, 11: 'list' => 5, 12: ) 13: ), 14: array( 15: 'condPrevValue' => '2', 16: 'GETvar' => 'tx_extrepmgm_pi1[display_cat]', 17: 'valueMap' => array ( 18: 'docs' => 10, 19: ), 20: ), 21: array( 22: 'GETvar' => 'tx_extrepmgm_pi1[showUid]', 23: 'lookUpTable' => array( 24: 'table' => 'tx_extrep_keytable', 25: 'id_field' => 'uid', 26: 'alias_field' => 'extension_key', 27: 'addWhereClause' => ' AND NOT deleted' 28: ) 29: ), 30: array( 31: 'GETvar' => 'tx_extrepmgm_pi1[cmd]', 32: ) 33: ), 34: '1383' => 'testPlaceHolder', 35: ),
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 "condPrevValue" 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/doc_core_cgl/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. |
Example
'lookUpTable' => array( 'table' => 'user_3dsplmxml_bfsbrand', 'id_field' => 'xml_id', 'alias_field' => 'xml_title', 'maxLength' => 10, 'addWhereClause' => ' AND NOT deleted' )
->actionConfig
| Key | Type | Description |
|---|---|---|
| type | string keyword | The action is identified by one of these keywords:
|
| Only type "redirect" | ||
| url | string | The URL to redirect to. There are two markers you can use in the URL:
|
Example: Redirects and required prefixes
1: 'redirects' => array( 2: => 'cms/', 3: 'mailinglist/' => 'http: //lists.netfielders.de', 4: ), 5: 'preVars' => array ( 6: array( 7: 'type' => 'action', // "type" action 8: 'index' => array( 9: 'cms' => , // Just bypass 10: 'admin' => array( 11: 'type' => 'admin' // Jump BE login OR setting frontend edit flags... 12: ), 13: 'search' => array( 14: 'type' => 'redirect', // Redirect... 15: 'url' => 'index.php?id=1344&tx_indexedsearch[sword]=###REMAIN_PATH###', 16: ), 17: 'ext' => array( 18: 'type' => 'redirect', // Redirect... 19: 'url' => 'cms/1383/list/###REMAIN_PATH###/index.html', 20: ), 21: '_DEFAULT' => array( 22: 'type' => 'notfound' // If key was not found in index, throw "404" not found. 23: ), 24: ), 25: ), 26: ),
In this example the the first segment of the URL is configured to be an action. The segment is required since the "type" of the "_DEFAULT" index is set to "notfound" meaning that if none of the other keys are matched you will see a "Page not found" error.
Anyways, the example takes offset in the typo3.org website and this is the consequences of the above configuration:
| URL | What happens |
|---|---|
| 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%5bsword%5d=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 |
Example: Language prefix and "admin" action
1: 'preVars' => array ( 2: array( 3: 'type' => 'action', // "type" action 4: 'index' => array( 5: 'admin' => array( 6: 'type' => 'admin' // Jump BE login OR setting frontend edit flags... 7: ), 8: 'search' => array( 9: 'type' => 'redirect', // Redirect... 10: 'url' => 'index.php?id=1344&tx_indexedsearch[sword]=###REMAIN_PATH###', 11: ), 12: 'ext' => array( 13: 'type' => 'redirect', // Redirect... 14: 'url' => 'cms/1383/list/###REMAIN_PATH###/index.html', 15: ), 16: '_DEFAULT' => array( 17: 'type' => 'bypass' // If key was not found in index, throw "404" not found. 18: ), 19: ), 20: ), 21: array( 22: 'GETvar' => 'L', 23: 'valueMap' => array( 24: 'dk' => '1', 25: ), 26: 'noMatch' => 'bypass', 27: ), 28: ),
In this example two preVars are configured, the first is an action containing almost the same actions as the previous example except that the "_DEFAULT" configuration is of the "bypass" type which means that if none of the key matches the first segment the interpreter will simply move on to the next preVar configuration for that segment (bypassing and adding segment value to stack again).
In addition there is a language prefix configured as well.
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/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 |
->pagePath
Configuration of the method that en/decodes the id to/from a "page path"
| Key | Type | Description |
|---|---|---|
| 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 |
Example of page id translation to path:
'pagePath' => array( 'type' => 'user', 'userFunc' => 'EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_advanced->main', 'spaceCharacter' => '-', 'languageGetVar' => 'L', 'expireDays' => 3 ),
Calls a user function which will render a true Speaking URL of the page titles and not just output the page id numbers. See a thorough description of this class later in this document, chapter "class.tx_realurl_advanced.php"
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/
Example of dummy setup:
'pagePath' => array( 'type' => 'user', 'userFunc' => 'EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_dummy->main', ),
Calls a dummy class which does exactly what the main class does: Outputs the page id/alias and nothing more. But if you want to implement your own schemes this class is a useful offset for you!
->postVarSet
| Key | Type | Description |
|---|---|---|
| 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! |
Example: Frontend edit
1: 'postVarSets' => array ( 2: '_DEFAULT' => array( 3: .... 4: 'edit_now' => array( 5: 'type' => 'admin' 6: ) 7: ), 8: )
Adding lines 4-6 in the above codesnippet to the postVarSets of a configuration will enable frontend edit mode if users append ".../edit_now/" to the virtual path. Of course you can choose any "admin-directory" you like.
One warning here; If the keyword is appended to a URL where a previous postVarSet sequence is not yet finished then the keyword will of course be seen as a parameter of that postVarSet and not as the keyword triggering the frontend edit mode as you wanted. Therefore you might want to use the same feature but for pre-vars instead.
Example: PostVarSets
1: 'postVarSets' => array( 2: '_DEFAULT' => array ( 3: 'plaintext' => array( 4: 'type' => 'single', // Special feature of postVars 5: 'keyValues' => array ( 6: 'type' => 99 7: ) 8: ), 9: 'ext' => array( 10: array( 11: 'GETvar' => 'tx_myExt[p1]', 12: ), 13: array( 14: 'GETvar' => 'tx_myExt[p2]', 15: ), 16: array( 17: 'GETvar' => 'tx_myExt[p3]', 18: ), 19: ), 20: 'news' => array( 21: array( 22: 'GETvar' => 'tx_mininews[mode]', 23: 'valueMap' => array( 24: 'list' => 1, 25: 'details' => 2, 26: ) 27: ), 28: array( 29: 'GETvar' => 'tx_mininews[showUid]', 30: ), 31: ), 32: ), 33: ),
This example shows how three sets of postVarSets has 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