Packages » Package freeform » File locationRewriter.txt

Package freeform, documentation file locationRewriter.txt

Location Rewriting in Freeform

Starting with the Freeform framework 1.2.0.Beta it is possible to rewrite URLs generated by the Location objects so that the real URLs can be hidden or made more search-engine friendly.

In fact, the rewriting of URLs involves two phases: first phase encodes the URLs contained in the responce douments, while the second phase decodes them at the beginning of every request. While the first phase is done by Freeform itself (i.e., by the class implementing the LocationRewriter interface), the second phase requires some processing by the web server (like mod_rewrite module or ErrorDocument directive in Apache). Sometimes this server processing will be enough, but depending on the rewriter you develop, it may be possible that some further transformation be done by the rewriter itself.

To enforce Freeform rewrite URLs created with the Location objects you will have to create a class that implements the LocationRewriter interface. Also you will have to add the locationRewriter configuration option to the freeform package .config file:

  locationRewriter=MyLocationRewriterImpl


The freeformdemo package contains two example location rewriters, FDLocationRewriter1 and FDLocationRewriter2 that can be used as a reference while developing your own rewriters. The first rewriter fully hides the real URLs and decodes them itself too; it does not use the mod_rewrite, but requires that a special error handler be set. The second rewriter creates more transparent URLs and requires that mod_rewrite is available at your host. Please refer to the documentation of FDLocationRewriter1 and FDLocationRewriter2 for more details.

In general, with Apache server you have two possible rewriting strategies:
  1. Use mod_rewrite
    If you server has the RewriteEngine=on, you can have it decode the encoded URLs, possibly doing some more processing by your LocationRewriter::decode() method.
  2. Use ErrorDocument directive
    If you do not have access to mod_rewrite, you can make your rewriter create "wrong" URLs that will result in HTTP 404 Not Found errors. These errors can be trapped by a special handler that will redirect the requests to a valid location. Please see the FDLocationRewriter1 docs and source for details.


Note
It is highly recommended that you enable rewriting or change the rewriter before the launch of a high-traffic site because many users that may be present at your site while you change the rewriter will face strange behaviour (i.e., links not working etc) on a page they see. While this is only one-time issue for a visitor (i.e, returning to home page will solve it), it may cause negative attitude to your site.

Also it is important to remeber that with rewriting enabled, you will not be able to manually create links to other actions with the <a> tag like:

  <a href="?action=MyHomeAction">Go to home page</a>


While this is not encouraged but possible when rewriting is disabled, you will have to use the HTMLLink tag in conjunction with a location object to create links. Optionally (if the action you want to link to does not accept parameters), you can use the action attribute to specify which action to link to.

In addition to that, rewriters that completely obscure the URLs cannot be easily used with GET forms as there is no way to force the browser rewrite URLs according to the rewriter rules. In such case the rewriter must be able to recognize non-encoded URLs and simply return the $_GET array. Rewriters that make just minor modifications to the URL (like removing the action parameter and the question mark) can be engineered in such a way that will allow them transparently handle both encoded and non-encoded URLs (like the FDLocationRewriter2), especially when the decoding is fully done by the mod_rewrite.