Fusebox 'relocate' Verb

The relocate verb is used to redirect the browser to a different URL and can employ either server-side or client-side redirection. In its simplest form, it looks like:

<relocate url="http://www.techspedition.com" />

The url attribute is required and can be an absolute or relative uniform resource locator.

One use of the relocate command is to prevent a user from unintentionally submitting a request more than once simply by hitting their browser's "back" button. You can imagine the havoc that could be wrought after a database insert if a user were to continue hitting "reload". A redirection command can help prevent that.

One optional attribute of relocate is the Boolean variable, addtoken, which operates much like the addtoken attribute of ColdFusion's cflocation tag. Since addtoken is true by default the following statements is equivalent to our first example:

<relocate url="http://www.techspedition.com" addtoken="true"/>

Developers can also choose between client-side redirection, which is the default, and server-side redirection by use of the optional type attribute. If this is available for the platform of the core files you are using, you can specify the redirection in the following way:

<relocate url="http://www.techspedition.com" addtoken="true" type="client"/>

or

<relocate url="http://www.techspedition.com" addtoken="true" type="server"/>

In CFMX, for example, the latter is the equivalent of:

<cfscript>
getPageContext().forward("http://www.techspedition.com");
</cfscript>

Developers should note that XML imposes certain restriction on a small set of characters, requiring them to be specified via their character entities. This is noticeable with the relocate verb since the common ampersand (&) character is one such entity, requiring URLs such as:

<relocate url="http://www.mydomain.com/index.cfm?fuseaction=users.listUsers&gender=female" />

This is just something to be aware of, and is imposed by the XML standard, not Fusebox. Of course, developers can always use generic fuses for redirection and then handle such redirection inside the fuse itself in whatever manner they prefer.

Fusebox 5.1 introduces type="moved" and type="javascript". "moved" causes a 301 Moved Permanently status to be returned to the browser along with the new URL as a Location: header. "javascript" causes some JavaScript code to be output that when executed in the browser will change the href of the current window to the new URL.