81 Using WebCenter Sites URL Assemblers

WebCenter Sites URL assemblers manage URL assembly and disassembly. You can use the interface that they provide to define the appearance of URLs.

Topics:

81.1 About WebCenter Sites URL Assemblers

You can use URL assemblers along with URL generation tags to generate WebCenter Sites URLs and to disassemble the URLs.

URL Assemblers are the legacy method of URL management. Vanity URLs are the current method. See Vanity URL Links in a Web Page.

Topics:

81.1.1 URL Assembly

WebCenter Sites URL generation tags (<satellite.link>, <satellite.blob>, <render.getpageurl>, <render.getbloburl>, <render.satelliteblob>, <rendergettemplateurl>) are used to construct a link to a WebCenter Sites resource, such as a page or a blob. The data, such as tag attributes and nested argument tags which you specify when using the tag, is converted into an abstract object called a URL definition. The URL definition is passed into the URL assembler. The URL assembler then converts the definition into a string URL that is returned.

Two assemblers are installed with WebCenter Sites, but you have the option of creating your own assemblers to directly control the appearance of your URLs. Before you can use the assemblers you create, you must first register them with WebCenter Sites.

The assembler that is configured as the default is used to create all WebCenter Sites URLs. You can change the default assembler. You can also override the use of this default assembler in individual link tags.

81.1.2 Assembler Discovery and Disassembly

Because an assembler can create a URL in any form that the assembler's author dictates, it may be impossible for the URL to be decoded into parameters by an application server when an assembled link is requested. For decoding to take place, the assembler must be able to disassemble the string URL into its definition. Assemblers are therefore reversible, that is, capable of disassembling any URLs that they assembled.

URL created using an assembler other than the default one can't be disassembled by the default assembler. At that point, the next highest ranked assembler attempts to disassemble the URL. If it succeeds in creating a definition, then the assembler engine has discovered its assembler, and the definition is converted into parameters for processing. If the next highest ranked assembler fails to disassemble the URL, the third highest ranked assembler is called upon to disassemble it. This process continues until the URL is successfully disassembled. Note that this process requires an assembler to be able to recognize the URLs it assembled as its own, and all other URLs as foreign.

See Creating Assemblers and Registering and Ranking Assemblers.

81.1.3 URL Assembly and Disassembly Using GET and POST Requests

URL assemblers are only invoked on GET requests. They are not invoked on POST requests. For example, when accessing a page with a GET request, the URL assembler is invoked to disassemble the URL. It then provides the appropriate parameters that WebCenter Sites requires to open that page (such as c, cid, and pagename) by adding them to the definition (if they do not exist in the definition). However, when a request is POSTed, such as a form with method=post, the URL assembler is not invoked to disassemble the URL. Therefore, the parameters WebCenter Sites requires to open the page must be part of the post request itself.

This can be accomplished by encoding the following tag into the page's template or element (replacing the sample values with the parameters WebCenter Sites requires for the page's URL):

<satellite:form method="post" id="assetid">
<render:gettemplateurlparameters list="args" ... /><!-- add all parameters that are normally part of a URL -->
        <ics:listloop listname="args">
               <input type="hidden" name="<string:stream list="args" column="name"/>" value="<string:stream list="args" column="value"/>"/>
        </ics:listloop>

81.2 Assemblers Installed with WebCenter Sites

The two assemblers that are installed with WebCenter Sites are Query Assembler and QueryAsPathInfo Assembler. While the Query Assembler uses query strings to create URLs, the QueryAsPathInfo Assembler encodes the query strings and appends them to the end of servlet names. 

Topics:

81.2.1 Query Assembler

The Query Assembler creates URLs with query strings. It is the default assembler, and it is automatically registered in WebCenter Sites. Therefore, until you make any modifications (such as changing the default assembler or overriding the default in link tags), Query Assembler is used to generate all URLs.

81.2.2 QueryAsPathInfo Assembler

The QueryAsPathInfo Assembler does not use query strings. Instead, the QueryAsPathInfo Assembler encodes the query string and appends it to the end of the servlet name. The benefit of this assembler is that it creates URLs that can be indexed by search engines. The QueryAsPathInfo Assembler is not automatically registered with WebCenter Sites.

81.3 Working with Assemblers

You can create and register your own assemblers and modify link tags to override the use of the default assembler.

Topics:

81.3.1 Creating Assemblers

The WebCenter Sites URL Assembly module enables you to create your own assemblers. This option gives you direct control of the appearance of your URLs.

To create an assembler:

  1. Write a Java class that implements the com.fatwire.cs.core.uri.Assembler interface. For information about this class, see the Java API Reference for Oracle WebCenter Sites.
  2. Compile the class into a .jar file.
  3. Deploy your class into the WebCenter Sites web application and the web application for each remote Satellite Server you have installed.

    This usually means copying the .jar file you just created into your web application's WEB-INF/lib folder. For remote Satellite Servers, this means copying it to the resin/webapp/ROOT/WEB-INF/lib folder.

  4. Register your new assembler in the wcs_properties.json file on WebCenter Sites and all of your remote Satellite Servers. (See Registering and Ranking Assemblers.)
  5. Restart WebCenter Sites and all of your remote Satellite Servers.

81.3.2 Registering and Ranking Assemblers

Before an assembler can be used to create URLs, it must first be registered with WebCenter Sites. The registration is done by listing assembler class names with corresponding short forms in a property file. The registration also includes a ranking that indicates in which order the assemblers should be used.

To register an assembler:

  1. In the Admin interface, open the Property Management Tool.
  2. In the Category drop-down menu, select ServletRequest to access the assembler properties.
  3. Click Search.
  4. Specify the classname and shortform of the assembler you want to register.

    The third element in the property name indicates the ranking of the assembler. The assembler with the ranking of 0 is the highest ranked (and default) assembler, the assembler with the ranking of 1 is the next highest ranked, and so on.

    To configure the new assembler to be the default assembler, enter the classname and shortform values in the properties that have 1 as their ranking.

    For example, the syntax to register the QueryAsPathInfo assembler as the default assembler would be as follows:

    Table 81-1 Assembler Properties

    Property Name Property Value

    uri.assembler.0.classname

    com.fatwire.cs.core.uri.QueryAsPathInfoAssembler

    uri.assembler.0.shortform

    pathinfo

    uri.assembler.1.classname

    com.fatwire.cs.core.uri.QueryAssembler

    uri.assembler.1.shortform

    query

    Note:

    Ensure the Query Assembler is always registered, even if you have lowered its ranking. The Query Assembler must be registered with the shortform value of query.

  5. Depending on the ranking of the new assembler, you may have to adjust the rankings of the other assemblers. Verify that all of the assemblers are configured and ranked correctly in the property file. If they are not, make any necessary changes.
  6. After you change the value of an assembler, click Save before modifying the value of a different assembler.
  7. Repeat steps 5 through 6 for each remote Satellite Server you have installed.
  8. Restart WebCenter Sites and all of your remote Satellite Servers.

81.3.3 Link Tags Modification

WebCenter Sites link tags can be modified to use an assembler other than the default assembler. The link tags accept an attribute, assembler, which take an assembler short form as a value. For example, to override the default assembler with the QueryAsPathInfo assembler in an individual link tag, the syntax would be as follows:

<satellite:link pagename=example assembler=pathinfo />

81.4 Vanity URL Links in a Web Page

If an asset has a vanity URL for the template that is passed in the name argument, then the <render:gettemplateurl> tag returns the vanity URL. If the asset does not have a vanity URL, then the tag returns the WebCenter Sites URL.

The <render:gettemplateurl> tag can be used to generate a vanity URL link. Thus any redirected URL always returns the vanity URL if present. That way, if an existing link is accessed (for example, from a bookmark), then all subsequent URLs are vanity URLs.

To generate a vanity URL for a specific WebRoot, an additional optional parameter called hostparam should be passed to render: gettemplateurl. The value of the hostparam should match the hostname attribute of WebRoot. This can be used to generate a link to another website or subdomain within the same website. For example:

<render:gettemplateurl outstr="pageURL" webrootname=<name of WebRoot used for retrieving URL> tname='<%=ics.GetVar("template")%>' args="c,cid" />