May 30, 2008

RealURL made easy: part 1

People often complain that RealURL is hard to configure. In my opinion it happens because RealURL manual is written as a reference guide, not like a tutorial. Therefore there is nothing for beginner to start from. Recent RealURL versions include automatic configuration, which is good for simple web sites.

However it is not flexible enough. Manual configuration would always win over automatic one. This article provides a simple guide for manual RealURL configuration. It is not short, so reserve some time for reading it.

The whole guide is divided to several parts. The first part describes configuration in general. Other parts will describe details, tips&tricks and best practices.

Basics

This section covers general principles of RealURL functionality.

RealURLed URL

Before we start with configuration, it must be clear what parts RealURLed URLs can contain.
Typical RealURLed URL consists from several segments:

Segments are (in the order of appearance):

  • preVars
    These are prepended to page path. Typically it is language identifiers. They should not be long.
  • Page path
    This is a path to the page. It is created by traversing a page tree from the root of web site to the target page. There are several fields that can be used to create segments. Typically it is page title, alias, subtitle and special RealURL field named “Path segment”
  • fixedPostVars
    These are non-prefixed parameters to the page. They are very similar to preVars but go after page path. Typically they are set for specific pages only, not for the whole site.
  • postVars
    These are prefixed parameters to the page. For example, tx_ttnews[tt_news]=5 can be converted to /news/test-news-item/. Here “news” identifies tx_ttnews[tt_news] and 5 is replaced by encoded news item title.
Each segment (except page path) can have several variables.

Configuration basics

Normally RealURL configuration is stored in the separate file. This file is usually included into typo3conf/localconf.php.

RealURL configuration is a nested PHP array. Configuration is created per a web site. Logically it looks like:

$TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(
  'www.domain1.com' => array(
    ...
  ),
  'domain1.com' => 'www.domain1.com',
  'www.domain2.com' => array(
    ...
  ),
  'domain2.com' => 'www.domain1.com',
  );

There are two types of entries here. Domain name can either point to another domain name or to a configuration array.

If domain name points to another domain name, RealURL will take configuration of the pointed domain. There can be several pointers in the chain.

If domain name points to an array, it is configuration. We will look to it in a moment.

If there is only one domain, there is no need to specify it name. The whole configuration then may look like:

$TYPO3_CONF_VARS['EXTCONF']['realurl'] = array(
  '_DEFAULT' => array(
    ...
  ),
);

This case is valid also if domain.com is an alias for www.domain.com.

The configuration array for each domain (or for _DEFAULT) consists from subarrays, called configuration sections.

Configuration sections

There are six configuration sections. None of them is mandatory but at least two are usually used. Here is a “bird view” to the sections:
  • init
    This section describes general RealURL options, such as caches, empty URL return value and some other options.
  • preVars
    This section defines preVars (see URL example above!). As simple as that.
  • fixedPostVars
    This section defines fixedPostVars.
  • postVarSets
    This section defines postVarsSets. This is the most trickier configuration part.
  • pagePath
    This section is usually copy/paste section. It does not change much between various servers. However it has one parameter (rootpage_id), which has ultimate importance in multidomain configuration.
  • fileName
    This section allows to end URLs with something like “rss.xml” or “print.html”. Mostly it is also copy/paste section.

Creating init section

init section normally contains cache configuration directives and some other useful options. Here is a short list that you should have in your configuration:
  • 'enableCHashCache' => true
    Use this if web site uses any extension with URL parameters. Details about cHash can be found here and here.
  • 'appendMissingSlash' => 'ifNotFile'
    This appends slash to the end of URL. Just looks nicer.
  • 'enableUrlDecodeCache' => true
    Enables to use fast database-based cache when user visits a page. This is a huge performance improvement comparing to when cache is disabled.
  • 'enableUrlEncodeCache' => false
    Same as above but for encoding. This is used when creating links. There is no reason why you may want to disable this or above cache. None at all.
This list is not complete. You can find some other directives in RealURL manual.

Making preVars section

The section consists from one or more parts. Each part is an array itself and it defines a single preVar. Example:

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

In this example, preVar is associated with “L” URL parameter. valueMap says that L=0 is mapped to /en/, L=1 is mapped to /de/. noMatch says that any other L value will be silently ignored.

It is possible to specify also default value or do other conversions. For details reader is encouraged to read RealURL manual.

Creating fixedPostVars section

fixedPostVars are very similar to preVars. There are only two differences:
  • fixedPostVars are placed after page path in URL.
  • fixedPostVars must have either a page id or _DEFAULT keyword (for all pages)
Take a look to example:

35 => array(
  array(
    'GETvar' => 'tx_myext_pi1[no_comments]',
    'valueMap' => array(
      'no-comments' => 1
    ),
    'noMatch' => 'bypass',
  )
),

Here there is one more wrapping array around real fixedPostVar definition. This wrapping array tells that page with id 35 has this fixedPostVar. So “no-comments” fixedPostVar will not apply to other pages (unless added also there). There is also 'noMatch' to skip this variable completely when it does not make sense to have it.

If there should be more than one fixedPostVar on this page, it will follow the first one like this:

35 => array(
  array(
    ...
  ),
  array(
    ...
  )
)

fixedPostVars will appear in the defined order. It is important to think about the order and keep it once it is defined or decoding will not happen properly.

Making postVars sets

postVarsSets look similar to fixedPostVars but they have prefixes that identifies a postVar. It allows to put postVars in any order in the URL. It also allows to have a very flexible set of postVars.

One postVar in the URL can actually define several real GET parameters. For example:

'_DEFAULT' => array(
  'myparam' => array( // postVar start
    array(
      'GETvar' => 'tx_mext_pi1[p1]',
    ),
    array(
      'GETvar' => 'tx_mext_pi1[p2]',
    ),
  ), // postVar end, Other postVar definitions may follow
),

Now, suppose non-encoded URL looks like http://domain.com/index.php?id=25&tx_myext_pi1[p1]=12&tx_myext_pi1[p2]=34

Encoded URL will look like http://domain.com/page/path/myparam/12/34/

It is even possible to convert numbers to strings if they refer to database tables. Also PHP code can be provided to map real GET parameters to encoded parameters and back. The system is extremely flexible and allows you do almost anything!

pagePath section

pagePath section is typically used to enhance RealURL even further. By default RealURL creates URLs like this http://domain.com/35/myparam/12/34/
To replace page id (35 in the example about) with a real path to page, the following content should be placed to pagePath section:

'type' => 'user',
'userFunc' => 'EXT:realurl/class.tx_realurl_advanced.php:&tx_realurl_advanced->main',

There are other directives. The most important of them is rootpage_id. This directive points to the page, which is the root (home page) of the current web site. It must be set for multidomain configurations and it is recommended to set it even in single domain configuration (or RealURL will have to find it). Forgetting this directive in multidomain configuration always results in incorrect RealURL behaviour!

fileName section

It is safe to skip this section in your configuration. Generally it is not needed unless you have to create nice looking ending file names in URL.

Conclusion

In this article we reviewed RealURL configuration. Next article will show how to make this configuration effective. It will show some tips and tricks that are not obvious from the manual and that you should know. So, watch this site for the next article!

31 comments:

  1. Excellent idea!



    I\'m looking forward to part 2, there\'s always something to learn...

    ReplyDelete
  2. Great!



    You don\'t know, how long i am waiting for this *gg*.



    Thank you, Dmitry!

    ReplyDelete
  3. Great article :)

    Thanks

    ReplyDelete
  4. I hoped you would like it ;)

    ReplyDelete
  5. Thanks, Dimitri. Wish I had seen this two days earlier but I will keep it bookmarked for later.

    ReplyDelete
  6. Thanks Dmitry. Great article. Waiting for part 2.

    ReplyDelete
  7. I m wait for part 2. Great article

    ReplyDelete
  8. Thank you Dimitry for this great tutorial. I\'ve a wish for the 2nd part :)

    How to exclude pages/sysfolders in the path?

    ReplyDelete
  9. Great, thank you for this tutorial!

    ReplyDelete
  10. Thank you ... this tutorial had really helped in the configuration.

    ReplyDelete
  11. Great work Dmitry. Thanks for sharing that with us.

    ReplyDelete
  12. Thank you ... this detailed tutorial was very helpful to me.

    ReplyDelete
  13. Excluding is not possible with default realurl, sorry :( I heard that aoe_realurl adds this functionality.



    Part 2 will be out soon. Hopefully this week or beginning of next week.

    ReplyDelete
  14. @Dmitry: aoe_realurl does this leaving out thing which is very usefull. But don't use aoe_realurl with a multilingual invironment.

    ReplyDelete
  15. hey

    http://domain.de/folder/subfolder/subfolder/keyword/xyz-xyz-xyz.html

    i want just

    http://domain.de/keyword/xyz-xyz-xyz.html

    is this possible with realurl?


    ReplyDelete
  16. Great tutorial!!

    ReplyDelete
  17. This Tutorial has me very helped for the configuration with realurl. Thanks!

    ReplyDelete
  18. Thank you, Dmitry! Very good tutorial.

    ReplyDelete
  19. I wish I had found this before burning through hours of searching, reading the manual and did trial and error (no success!). Thanks.

    ReplyDelete
  20. Currently RealURL can skip segments too (there is a checkbox in the page properties). And it still works in multilanguage environment :)

    ReplyDelete
  21. Hi Dmitry,



    Thank you for great tool and for very useful articles/tutorials.



    I was looking for the solution, how to use several table fields in alias_field. I did not find anything in manuals so I decided just to use MySQL CONCAT function:

    ...

    'alias_field' => 'CONCAT(name1,\'-\',name2)',

    ...



    It works ok. But I just wonder if there is any native realURL solution for that?



    Thank you,

    Stas

    ReplyDelete
  22. Thanks very much for these guides Dmitry. It made configuring RealURL easy, just as you said.

    ReplyDelete
  23. Karin HinterleitnerSeptember 3, 2009 at 2:05 PM

    Written very comprehensible - even for non MySQL/PHP nerds! Thank you so much - you helped me a lot!

    ReplyDelete
  24. Hi! Can I configure the extension to use in a more complex way? I want most of the pages to be referenced without freandly urls i.e. www.yourdomain.com/index.php?id=2 and other pages with a friendly urls i.e. www.yourdomain.com/contact.

    ReplyDelete
  25. Any idea how I could make a fixedPostVar multilanguage?



    In your example: no-comment (english) / keine-kommentare (german)



    Thanks.

    ReplyDelete
  26. How do I get all the old versions of realUrl extension?

    Thanks.

    ReplyDelete
  27. [url=http://www.google.com/]google[/url]

    ReplyDelete
  28. thank you Dimi... this (reaurl) can work also with TV... thank you for all the good work... the tips and the help you give to us (non-programmers) thanks !!!! ... I still working on the page browser (universal browser) is not working with TV :((( ... i hope tha you will make some miracles to get it "done":)))... or if you can help me to make it work it will be great...



    thanks again

    ReplyDelete
  29. Is it possible to get the following work with realurl:



    &tx_ext_pi1[areafilter][3]=on&tx_ext_pi1[areafilter][1]=on&tx_ext_pi1[areafilter][2]=on&tx_ext_pi1[areafilter][4]...ANDSOON



    I mean i have a parameter "areafilter" which is an array itself and can have different items...

    ReplyDelete
  30. Fantastic article. Exactly what was needed.

    ReplyDelete