Skip to content

Notes for Integrators

Jump to bottom
Dmitry Dulepov edited this page Jun 20, 2016 · 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. Not 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

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

TypoScript

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

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

Cache clean up

(RealURL ≥ 2.1.0)

RealURL manages caches efficiently and does not need manual clean up. However you can keep RealURL healthy by adding two scheduler tasks that will remove expired entries. Task name is "Table garbage collection (scheduler)". Two tasks has to be added (one per available table). Here is how it should look like in the scheduler:

-- img here --

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.

Starting from version 2.0.8, realurl will re-configure TYPO3 to prevent creation of pages with the same title in the same parent page. However it cannot detect or prevent collisions in case if some pages are excluded. If such pages already exists, it is an error for realurl and must be solved by the integrator.

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 found a bug...

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

The first thing you do is you ask in the TYPO3 mailing lists. 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