|
|
|
URIUtils
URIUtils is a set of APIs for constructing relative and absolute URIs within a Zero application. These APIs are helpful when constructing URIs for many purposes, including hyperlinks, images, and CSS links.
Why page-relative URIs are recommended
In general, page-relative URIs are recommended since they are independent of reverse-proxy URI mappings and mash-up scenarios. However, one must take care in constructing these URIs.
A "broken" page
Consider a simple illustration with greeting.gt, which returns an HTML page containing three images:
<!-- greeting.groovy: Version 1 -->
<html><body>
Hello world.
<img src="http://host/images/absolute.jpg">
<img src="/images/root.jpg">
<img src="images/page.jpg">
</body></html>
Now look at what happens when the page is requested under three different scenarios:
| Scenario | Client request | Client tries to access images at... |
|---|
No context root;
exact request | http://host/greeting.gt | http://host/images/absolute.jpg
http://host/images/root.jpg
http://host/images/page.jpg |
No context root;
request with path info | http://host/greeting.gt/more | http://host/images/absolute.jpg
http://host/images/root.jpg
http://host/greeting.gt/images/page.jpg |
Context root (/sample) | http://host/sample/greeting.gt | http://host/images/absolute.jpg
http://host/images/root.jpg
http://host/sample/images/page.jpg |
The first scenario works fine, but the other two scenarios fail with "broken" image references.
In the second scenario, the page-relative link (page.jpg) fails because the user agent resolves it with the request URI, including path info.
In the final scenario, the absolute URI (absolute.jpg) and root-relative URI (root.jpg) fail because they are sensitive to changes in deployment.
A robust page
A more robust page will be one that uses page-relative links that are adjusted for path info. URIUtils provides a means to construct these links with the getRelativeUri() API:
<!-- greeting.groovy: Version 2 -->
<html><body>
Hello world.
<img src="<%= getRelativeUri("/images/absolute.jpg") %>">
<img src="<%= getRelativeUri("/images/root.jpg") %>">
<img src="<%= getRelativeUri("images/page.jpg") %>">
</body></html>
Note that the leading slash in the argument to getRelativeUri() is significant:
- With a leading slash, the argument is considered relative to the application root without Zero's context root. You could think of this as specifying a URI starting from the
public folder of your application.
- Without a leading slash, the argument is relative to the calling script.
API reference
URIUtils includes the following utility APIs:
public static String getRelativeUri(String path) { ... }
public static String getRelativeUri(String path, Map<String,String> queryParms) { ... }
public static String getRelativeUri(String path, Map<String,String> queryParms, String fragment) { ... }
public static String getAbsoluteUri(String path) { ... }
public static String getAbsoluteUri(String path, Map<String,String> queryParms) { ... }
public static String getAbsoluteUri(String path, Map<String,String> queryParms, String fragment) { ... }
public static String getRequestedUri(boolean includeQueryString) { ... }
Usage details may be found in the Javadoc.
|
