The "return_url" Web-Pattern

This "pattern" or programming style addresses a frequent issue in Web-applications.

Page Flows

One or more Web pages form a "page flow", i.e. a logical unit of pages that belongs together. The most simple flow is the combination of an "EditPage" (a page showing information about an object in a form) and a "SavePage" (a page saving the modified data to a database). More complex flows include "wizards", workflows etc.

The Anchor Page

Most of these flows start off from a certain page, which we want to call anchor page. The intuitive behavior of the application is return to this initial page once the flow has successfully terminated. However, a flow may be called from more then one anchor page. So the last page of a flow usually contains a quite ugly logic to calculate where to return.

The idea of the "return_url" pattern is to avoid this ugly logic and to replace it by a single parameter provided by the anchor page (or more general: page that initiates the flow).

Passing "return_url" Along

Nearly all pages in OpenACS and ]project-open[ contain this (in-) famous "return_url" in one or more places. There are two main places:

1. In the Link at the Anchor Page
   It is the responsibility of the anchor page to "call" a flow with the URL of the anchor pages as return_url.
   This is a kind of "inversion of control": Instead of the flow, it is the anchor page that tells the flow to return to the page.
   
   
2. In the "Page Headers" of the "flow" pages
   The code "{ return_url "" } is found in the "Page Header" of most ]project-open[ page. The "Page Header" is like the declaration of parameters of a procedure, only that it takes its variables via URL or HTTP POST commands. It is particularly nice that you can specify a default value for the return_url if it shouldn't have been specified explicitly by the user/application
   
   
3. In the forms & links of the flow pages
   Each flow page needs to pass the return_url to the next page. OpenACS/]po[ has several commands such as "export_form_vars" that automate this task, for both forms and links.
   
   
4. At the last flow page
   The last page of a flow executes a "ad_returnredirect $return_url" command as the very last action. This commands will redirect the browser back to the anchor page
   

Code Samples

For code samples please see any ]project-open[ package and search for "return_url". You can download the source code of ]po[ from SourceForge at the download section of http://sourceforge.net/projects/project-open/.

Summary

This "return_url" pattern is definitely no rocket science. However, this simple "inversion of control" frees the flow pages from ugly, obscure and difficult to maintain logic and allows page flows to be reusable for different anchor pages.

Or to put it in another way: Any rooky still coding "page flow controllers" should know that there are more elegant solutions out there...