Skip to content

Notes for Integrators

Jump to bottom
Dmitry Dulepov edited this page Nov 14, 2019 · 24 revisions

Tips

FAQ

Tips

Configuring root pages for RealURL

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. Note that there should be all possible domains. For example, if you add example.com and forget another.example.com, than 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 Configuration reference for more information.

Home page, root page and shortcuts

Many people use a shortcut page named something like Home on the first level of the site to make home page appear in menu. There are two ways to make it:

  1. Make root page a shortcut to a page named Home inside the root page. In this case the content of the site home page is not on the root page but on the page named Home on level 1.
  2. Put content of the home page to the root page and create Home page on level 1 as a shortcut to the root page.

RealURL will work correctly only if you use the second way. If you use the first way, your URLs will look like /home/ for the home page (not / as you may expect) and subpages on the first level may look like /home/subpage/).

To repeat, the proper way:

  • Put content of the home page to the root page
  • Make a subpage named Home as a shortcut to your root page.

Configuring languages

Note: you have to follow these instructions exactly. Doing otherwise most likely will cause you troubles.

There are two ways people use languages with RealURL. Assuming that main language is German and secondary is French, here are two possible scenarios.

First scenario is when default language is omitted from URL. Example URLs will look like:

  • German: /ernaehrung/rezepte/rezeptsuche/
  • French: /fr/alimentation/recettes/recherche-de-recettes/

Second case is when default segment also present:

  • German: /de/ernaehrung/rezepte/rezeptsuche/
  • French: /fr/alimentation/recettes/recherche-de-recettes/

Selection is up to the integrator and its customer. RealURL allows both.

For the first case you configure RealURL as follows.

RealURL configuration

'preVars' => array(
  0 => array(
    'GETvar' => 'L',
    'valueMap' => array(
      'fr' => 1,
    ),
    'noMatch' => 'bypass',
  ),
),

TypoScript

config {
  sys_language_uid = 0
  language = de
}

[globalVar = GP:L = 1]
config {
  sys_language_uid = 1
  language = fr
}
[global]

For the second case configuration is different:

RealURL configuration

'preVars' => array(
  0 => array(
    'GETvar' => 'L',
      'valueMap' => array(
        'de' => 0,
        'fr' => 1,
    ),
    'noMatch' => 'bypass',
  ),
),

TypoScript

config {
  sys_language_uid = 0
  language = de
  defaultGetVars {
    L = 0
  }
}

[globalVar = GP:L = 1]
config {
  sys_language_uid = 1
  language = fr
}
[global]

Note: if you do not configure languages like described here, you will not get correct URLs with realurl. It is not a bug. It just how it works.

Limitations

Page titles

RealURL cannot correctly decode URL if there are two pages on the same level inside the same parent page because it is an ambiguity. Example:

Home
|- News <-- standard page
|-- Single <-- standard page
|- News <-- folder
|-- Corporate <-- standard page

Here /news/corporate/ may not be available unless its entry exists in the cache. Decoding for news/corporate will fail.

When excluding pages from URL, similar rules apply:

Home
|- Company <-- standard page but excluded
|-- News <-- standard page
|--- Single <-- standard page
|- News <-- folder
|-- Corporate <-- standard page

Here news/single may not be decoded unless it exists in the cache. For realurl news/ is a folder in this page tree! Only of the News page is absent on the level, where the excluded page exists, will realurl search under excluded pages.

Page types

RealURL does not decode subpages of the following page types:

  • Separator. Separator pages are just visual separators in the menu. They should not have subpages. Use folders instead. This is a breaking change since realurl 1.x. It is made to enforce proper page tree structure.
  • Recycler. Pages in the recycler are not visible on the site.

FAQ

How do I set 'L' to the default language value without using it in the URL?

You should use both RealURL and TypoScript for that. RealURL configuration will look like:

array(
	'GETvar' => 'L',
	'valueMap' => array(
		'fr' => 1,
		'it' => 2,
	),
	'noMatch' => 'bypass',
),

TypoScript will look like:

config {
	language = de
	sys_language_uid = 0
}

[globalVar = GP:L = 1]
config {
	language = fr
	sys_language_uid = 1
}
[globalVar = GP:L = 2]
config {
	language = it
	sys_language_uid = 2
}
[global]

My record titles are not unique. How do I use them in aliases?

RealURL appends numbers in such cases. However if you clear caches, URLs may change because numbers are appended on "first come – first served" basis. If you want to ensure unique URLs, use uid as a part of the alias:

array(
	'GETvar' => 'tx_myext_plugin[uid]',
	'lookUpMap' => array(
		...
		'alias_field' => 'CONCAT(title, '-', uid),
		...
	)
)

Excluding pages does not work

It does but there is one case where it seems like it does not. The rule: if the page is the current page, it will not be excluded from the path even if the corresponding checkbox is set in page properties.

Example:

|- Home (id=1)
|-- News (id=2)
|--- Detail (id=3)
|-- Test 1

Path to news items in such cases usually look like /news/detail/news-item-title/ (assuming you use fixedPostVars for news parameter). Typically people want to get rid of the detail segment. However it is not possible.

Technical reason is quite simple. Given the path /news/news-item-title/, what page is expected here? Is it a page with id=2 or a page with id=3? If you think that id=3, than what is the id for the /news/ path? Is it 2 or 3? Since RealURL cannot distinguish between such cases, the current page path segment cannot be excluded from the URL. If you have troubles what is current, think of the last segment of the page path (the one before news item title in the example above).

My URLs still look like /index.php?id=12345. What's the problem?

You forgot to enable RealURl in TypoScript using

config.tx_realurl_enable = 1

My URLs look like /46/. What's the problem?

This does not happen with RealURL 2.x anymore. Upgrade from version 1.x to 2.x.

RealURL does not work!

It does. Please, check you configuration and ask questions in TYPO3 mailing lists.

I see a lot of strange entries in the realurl module

Often people report a "bug" that they see strange values in realurl data in the Backend. For example, they see URLs with and without cHash or see strange L values.

This is not a bug in realurl. Actually it is not related to realurl at all. It is about how you configure your site.

Realurl only converts urls that it receives from TYPO3. So if a "bad" URL appears in the realurl data, it means that TYPO3 asked realurl to encode such URL. This means that there is a piece of TypoScript, or a Fluid template, or a Fluid viewhelper, or PHP code that makes such "bad" URLs.

It is essential to understand these two points, so here they are again:

  1. Realurl only encodes what it gets from TYPO3
  2. Realurl has no way to know whether the URL is correct or not. It always encodes it as is and passes the encoded version back to TYPO3.

Why can such "bad" URLs appear? Usually they come from improper configuration in the TYPO3 implementation. Usually:

  1. config.linkVars does not have proper restrictions for the L parameter.
  2. The site uses typolink.addQueryString that bypasses config.linkVars completely and can add any query string parameters to your links. The best thing to do is to avoid typolink.addQueryString completely or at least add an option to exclude some values like typolink.addQueryString.exclude = L,cHash. But this does not guarantee exclusion of any other arbitrary parameters. So this option should be avoided. Note that some Fluid viewhelpers use it, so issues may come from there too.

These problems are not unique for realurl. Even if you completely disable realurl, you may still have pages with wrong links due to points above. What you have to do is to be really careful and watch what you use and how. Security is very important these days and it should not be treated lightly.

I found a bug...

I can add very little to this classic writing...

The first thing you do is you ask in the TYPO3 Slack channel. If nobody else has this problem, than you have to double check that you do everything correctly (configuration, root page flags, database up to date, etc). Only than you write it in the bug tracker and put as many details as you can.

Clone this wiki locally