RikuloRikulo

The forward tag

Syntax 1

[:forward "a_uri" name1="value1" name2="value2" /]

Forwards to the given URI.

The URI can contain a query string. Furthermore, the arguments, if any, will be appended to it as part of the query string. You can retrieve them by use of HttpRequest.queryParameters.

The request handler returns immediately after forwarding. In other words, the content after the forward tag won't be generated.

Notice that the tag must end with /].

Syntax 2

[:forward method_name name1="value1" name2="value2" /]

Or,

[:forward method_name name1="value1" name2="value2"]
  [:var name3]
  ...any content including the include, for, and other tags
  [/var] [/forward]

Forwards the content generated by the given method, which is usually another RSP template. The content following the forward tag won't be generated.

The attributes specify the values for the additional named parameters. You can specify an expression ([=expression]) as the attribute's value.

You can also use [:var] to assign the dynamical generated content such as:

[:forward foo flag="[=true]"]
  [:var detail]
    <h2>The details</h2>
    [:include "details.html"/]
  [/var]
[/forward]

In the above example, we assume flag and detail are two named parameters of the foo closure. In addition, flag is bool and detail is String:

void foo(HttpConnect connect, {bool flag, String detail}) {
  ...

As shown, you can put any content in [:var].

Differences between include and forward

  1. The RSP page returns immediately after [:forward] executes. In the other words, none of the succeeding content will be rendered to the output after [:forward].

  2. Any updates to HTTP headers in the included page will be ignored, while the forwarded page is allowed to update the headers. Thus, it is OK to write any content before and after [:include]. It also implies before calling [:forward], no content shall be output. Otherwise, it will cause an exception if the forwarded page updates the HTTP headers.

Notice that whitespaces at the beginning of a RSP file won't be generated, so it is OK to have other tags before [:forward]. For example,

[!-- make sure no non-whitespaces before :forward --]
[:if !isAuthenticated() ]
  [:forward "/login" /]
[:/if]

where the whitespaces before [:forward] won't be generated.