Follow the basic guidelines below in any portlet that uses the Plumtree .NET Web Control Consumer:

• Name all elements uniquely.
• Do not assume your code is in a particular location in the HTML DOM.
• Do not rely on back/forward buttons or JavaScript commands.
• Do not access validator spans directly.
• Use FlowLayout instead of GridLayout.
• Always include the target page in the gateway space.

For more information and additional best practices, see the sections that follow.

The .NET Web Control Consumer module enables the use of .NET Web Controls and their associated AutoPostBack function. All automatic postbacks are caught and used to repaint the individual portlet. The module makes a number of modifications to the HTML; below is an overview of the modifications you should be aware of:

• All POSTs are handled by JavaScript, so they do not become part of the browser history. This means that JavaScript functions will not work; the Back and Forward buttons of the browser will skip any clicks made on Web Controls that are handled in this way.
• All requests from a portal server are transformed; navigating to the portlet directly does not yield the same HTML that is returned to the portal server. This allows the ASPX page to be accessed directly if required (the modified page would not function outside the portal environment). To examine the HTML going to the portal server, use a trace tool between the portal and the portlet server to intercept the HTML.
• All client-side validation script is transformed, but since ASP.NET only generates client-side script for specific versions of Internet Explorer (IE), nothing is altered for browsers other than IE.
• All .NET portlets are wrapped in an HTML <span>. Do not assume that the portlet is at any specific point in the HTML structure of the page; portlet parent elements are usually HTML table cells, but not in this case.
• The _doPostBack method is removed (a similar function is included in an additional JavaScript file). Beware of hooking into this .NET-provided function directly; both the function name and argument list are modified. Any direct calls to this function should also be modified automatically, however any non-standard calling conventions could potentially not be recognized by the module. To programmatically perform a postback from JavaScript, make the call _doPostBack('','');.
• Always use FlowLayout because GridLayout uses absolute positioning.
• The names for HTML spans (for validators) and forms (required for all pages that perform a postback) are appended with a unique ID (portlet ID), to avoid naming collisions on a portal page. Do not refer to these names directly in JavaScript. (If it is absolutely required, you can assume that they will be named <original-name>_<portlet-id>.)

Generally all HTML elements should be named uniquely, which normally involves appending the portlet ID to the element name. This can be problematic with ASP.NET, because the Web Control names and IDs cannot be generated at runtime in the normal ASPX syntax. For example the following code will not work:

<asp:Button id="Execute_<%= portlet_id %>" runat="server" Text="Test"></asp:Button>

The best way to append the portlet ID to the name is programmatically. To do this, declare the control in the ASPX page with a standard name, and then modify the ID property from the code behind page. You can access the actual controls using the System.Web.UI.Page Controls property or the System.Web.UI.Page FindControl(string ControlName) method.

For example, to append the portlet ID to a control named "MyButton," the following code could be employed:

protected override void OnPreRender(EventArgs e)
{
	base.OnPreRender (e);
	FindControl("MyControl").ID += portletID;
}

In most cases, submit buttons will be modified to remain in the portal context. This was not the case in the 2.1.x release; in that release, they required an additional ptrender attribute. This now defaults to true, although it can be disabled by adding a ptrender=false attribute to the button.

Each page refresh dynamically writes the HTML to re-render the portlet, so custom JavaScript can pose a problem. Because any JavaScript is now executing as the portlet is rendering, there are some functions that will not work correctly. Any document.write(..) calls will not work. To call a script each time the page is refreshed (or every time the portlet is re-rendered), use the rerenderPortletID event in the ALI Scripting Framework. This event is available only to .NET portlets and is named using the current portlet ID. For example, to create a JavaScript alert each time the portlet is rendered, use the code below.

<pt:namespace pt:token="$$PORTLET_ID$$" xmlns:pt='http://www.plumtree.com/xmlschemas/ptui/'/>
function alertMe_$$PORTLET_ID$$, () {
      alert("Portlet Rendering!");
}
alertMe_$$PORTLET_ID$$;//call the first time the portlet is loaded

Then register for the event in the code behind page:

private void Page_Load(object sender, System.EventArgs e)
{
	if(!IsPostBack)
		RegisterClientScriptBlock("rerender", "<script language=\"javascript\">document.PCC.RegisterForWindowEvent('rerender.$$PORTLET_ID$$', alertMe_$$PORTLET_ID$$)</script>");
}		

In the example above, $$PORTLET_ID$$ is replaced by the portlet ID using the pt:token tag. You can also use the IDK to extract the portlet ID from the request. See the AquaLogic Interaction Developer Documentation for more information on adaptive tags.

Under some circumstances, it may be desirable to disable HTML filtering. Pages opening in popup windows or operating in gatewayed mode will probably not want any HTML modification. Filtering can be disabled per-request by making the following call:

Context.Items["PTWC:EnableFilter"] = false;

This will disable filtering for the current request only.