RikuloRikulo

The include tag

Syntax 1

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

Includes 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.

Notice that the tag must end with /].

Syntax 2

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

Or,

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

Includes the content generated by the given method, which is usually another RSP template. 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:

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

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]. It allows you to define page fragments which can be assembled into a complete page at runtime. For more information, please refer to Templating: Composite View Pattern.

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.