edocs Home      dev2dev Home      Dev Centers      CodeShare      Community      Newsgroups     

Pagelet and Portlet Development: Adaptive Pagelets

Adaptive Tags: Common Tags

The Common Tag library rovides access to useful functionality, including URL transformation and namespace definition. This library also allows you to insert error information in the page, and CSS and JavaScript references in the Head element in a gatewayed HTML page.

Defining a Unique Namespace Token (Pagelet/Portlet ID)

It is established best practice to include the pagelet/portlet ID in the name of any Javascript functions and HTML elements to ensure unique names when the code is combined with markup from other pagelets on an aggregated page (i.e., My Page or Community). The pt:common.namespace tag allows you to define your own token (in the pt:token attribute), which is replaced with the pagelet/portlet ID. In ALI 6.1 and earlier, this tag is implemented as pt:namespace.

• Valid values for the token must be in the ASCII range 0x21 to 0x7E, excluding "<" (0x3C).

• The scope of the token runs from the tag defining it to the end of the file; you cannot use a token prior to defining it.

• A second pt:namespace tag with a different token redefines it; two tokens cannot be defined at the same time.

<pt:common.namespace pt:token="$$TOKEN$$" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>

<a onclick="doStuff$$TOKEN$$();" href="#">do stuff</a>

<script>
function doStuff$$TOKEN$$() {
alert("hello");
}
</script>

URL Transformation

The pt:common.url and pt:common.transformer tags allow you to create and manipulate gatewayed URLs. (For details on URL transformation and the gateway, see Portal to Remote Server Communication.)

Note: In ALI portal 6.1 and earlier, these tags are implemented as pt:url and pt:transformer. This syntax is still supported.

The pt:common.url tag is used to transform URLs that should be gatewayed. If the URL in the pt:href attribute is outside the gateway, it will be transformed to an absolute URL. This feature does not generate a link in HTML; it obtains the URL as a string and passes it to a client-side function, as shown in the following example.

<script>
function myFunction()
{
document.write("<pt:common.url pt:href="myURL" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>");
}
</script>

The pt:common.transformer tag allows you to turn off JavaScript URL transformation in a gatewayed page. Set the pt:fixurl attribute to "off" as shown below.

<pt:common.transformer pt:fixurl="off" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>

The transformer will not insert calls to the JavaScript URL transformation function for the rest of the file, unless you switch the feature back on in a subsequent directive (with a pt:fixurl attribute of "on").

Error Tags

The error* tags in the Ensemble Common library allow you to insert and format error messages within the page that contains the tag(s). For details on using these tags in custom error pages, see Creating Custom Login Pages.

The pt:common.error tag displays errors on the page, placed and formatted as desired. If the pt:common.errortext tag is included inside this tag, the contents of the tag will only be processed if there is an error. If the child tag is not present, any error messages will be formatted and displayed from this tag in the standard style.

If the pt:common.errortext tag is included, only the first error message will be displayed. Other errors, as well as exception stack traces and extended error messages, will be ignored.

The pt:common.errorcodes tag stores a collection of the current error codes in memory. If the error has already been displayed, no error codes will be available. These error codes can be accessed using the pt:logic.foreach tag as shown below.

Note: If these tags are displayed on a page, errors will no longer be displayed in the normal error location and will not be available after the tag has been displayed.

<pt:common.errorcode pt:key="errorcodes"/>
<pt:logic.foreach pt:data="errorcodes" pt:var="code">
<pt:common.errortext/>

Header Content

The pt:common.includeinhead tag marks JavaScript and CSS information to be included in the Head element of the HTML page by the pt:common.headincludes tag. If a .js or .css file is marked for inclusion multiple times, it will only be included once. JavaScript generated by tags will also be included. This tag will be ignored during automatic in-place refresh requests. Custom in-place refresh solutions must ensure that JavaScript gets included correctly.

<pt:common.includeinhead>

  <script type="text/javascript"><!-- JavaScript --></script>
<script type="text/javascript" src="http://test.com/test.js"></script>
<link type="text/css" rel="stylesheet" href="http://test.com/test.css"></link>

</pt:common.includeinhead>

The pt:common.headincludes tag adds JavaScript and stylesheet include information defined by the pt:common.includeinhead tag to the Head element of the HTML page, as required by the XHTML specification. If no pt:common.headincludes tag is present, JavaScript will be included at the bottom of the Head element, and a Head element will be inserted if one does not exist.

<head>
<script type="text/javascript" src="http://test.com/main.js"></script>
<pt:common.headincludes/>
</head>

The pt:common.jstransform tag inserts the ALI Scripting Framework headers into the Head element of the HTML page.

User Information

You can use Adaptive Tags to access specific user information settings. The name attribute is case sensitive.

The pt:common.userinfo tag is replaced with the value of the User Information setting specified in the pt:info attribute. In ALI 6.0 and 6.1, this tag is implemented as pt:userInfo with the attribute pt:name. This syntax is also supported.

<pt:common.userinfo pt:info="FullName" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>

Note: You must configure the Web Service (ALI) or Resource (Ensemble) to send the appropriate user information settings to the pagelet/portlet.

For a full list of tags and attributes, see the TagDocs.