rewriteUrl method

String rewriteUrl (String iUrl, { bool includeSession })

Convert an internal URL to a URL that can be used by a browser.

An internal URL is one that starts with "~/". This method converts that to a URL that can be presented (e.g. written in a HTML HREF attribute). If there is a session and session cookies are not being used, URL rewriting is performed (i.e. the session identifier is added as a query parameter).

For sessions to be preserved when cookies are not being used, all URLs referencing the application's pages must be processed by this method. If a link is not processed, then the URL rewriting does not occur and the session will not be preserved.

The concept of an internal URL serves two purposes. The main purpose is to try to force all URLs through this method; making it more difficult to forget to rewrite the URL. The second purpose is to make it easy to change the path to the entire application by changing the Server.basePath of the server.

A good way to check if all URLs are internal URLs that have been properly processed is to change the Server.basePath and test if the application still functions properly. If there are broken links, then those links were not defined as internal URLs processed through this method.

The includeSession parameter indicates if the session is added as a query parameter. The default value of "null" causes it to be only added if there is a session and cookies are not being used. If it is false, it is never added. There is no good reason to ever use it with true.

The [includeSession[ should be left as null in all situations, except when used for the "method" attribute of a HTML form element. In that situation, set it to false and use Request.sessionHiddenInputElement to preserve the session. See RequestImpl,sessionHiddenInputElement for details.

Note: this method is on the request object, even though it ultimately affects the HTTP response. This is because the request object carries the context for the request and the response. The session is a part of that context.

Implementation

String rewriteUrl(String iUrl, {bool includeSession}) {
  if (!iUrl.startsWith("~/")) {
    throw new ArgumentError.value(
        iUrl, "rUrl", "rewriteUrl: does not start with '~/'");
  }

  final buf = new StringBuffer(server._basePath);
  if (!server._basePath.endsWith("/")) {
    buf.write("/");
  }

  if (iUrl != "~/") {
    buf.write(iUrl.substring(2)); // append rUrl without leading "~/"
  }

  if (session == null ||
      (_sessionUsingCookies && includeSession != true) ||
      includeSession == false) {
    // Don't include the extra query parameter, because:
    // - there is no session to preserve;
    // - there is a session, but cookies are being used to preserve the
    //   session (and includeSession is not explicitly true); or
    // - invoker explicitly asked to not include it.
    return buf.toString();
  } else {
    // Append extra query parameter to preserve session
    final result = buf.toString();
    final separator = (result.contains("?")) ? "&" : "?";
    return "$result$separator${server.sessionParamName}=${session.id}";
  }
}