|
|
Portal Guide |
This chapter describes basic techniques for writing portal pages. It includes:
A Director portal application can include any of the following kinds of presentation objects:
All of these presentation objects can use Director components to present information to the user. From the user's point of view, each of these objects looks like a separate portal page.
PID pages, user pages, and group pages are served by the base servlet (PortalControllerServlet). JSP pages and servlets bypass the base servlet.
NOTE: A portal application can also contain static HTML pages, which do not use Director components. This chapter does not discuss static HTML pages.
A portal application can contain JSP pages. JSP pages are pages that conform to the JavaServer Pages (JSP) specification. This version of Director supports pages that conform to the JavaServer Pages 1.1 specification.
JSP combines the power of Java with the ease of use of a Web markup language. With JSP, you can author dynamic Web pages by adding simple markup elements (tags) to a page. Where necessary, you can also extend the capabilities of the page by including calls to JavaBeans components as well as embedded Java code fragments.
JSP technology builds on the Java Servlet architecture. To get the most out of JSP, you need to have a good understanding of the Java Servlet API.
For complete details on JSP and the Java Servlet API, see the Sun documentation.
Where to put your JSP pages You should package your JSP pages in a WAR file that is bound to a resource set that contains your Director resources. Typically your WAR will be configured to use an internal resource set. The JSP pages should be at the root of the WAR, or in a subdirectory of the root. They should not be stored inside the resource set, or anywhere inside the WEB-INF/lib directory.
Hot loading JSP pages JSP pages are not managed by resource sets. Therefore, the hot loading support provided with resource sets does not apply to JSP pages. However, you can use the rapid deployment capabilities of Workbench and the JSP/FS feature of the Novell exteNd Application Server to speed the process of developing and testing JSP pages.
For details about rapid deployment, see the chapter on archive deployment in the Tools Guide in the exteNd Workbench help.
For more information on JSP/FS, see the chapter on JSP deployment to the file system in the Facilities Guide in the Novell exteNd Application Server Core Help.
Director provides a set of tag libraries for use with JSP pages. These tag libraries include custom tags that wrap many of the most commonly used methods in the Director API. For example, they give the JSP author the ability to display PID pages and Director components, as well as to fire rules and access documents in the Content Management subsystem.
For example, a JSP page could use the displayComponent tag to display a portal component tag on the page. The displayComponent tag specifies a component ID, which provides the ID of the component, as well as a component instance name, which uniquely identifies the component on the page. In addition, if necessary, it can specify one or more custom parameters that alter the behavior of the component. A custom parameter is an arbitrary pairing of a name and a value that a particular component recognizes and uses.
The ID of a component is the name given to the XML file (without the extension) that describes the component. For example, if the XML file name for a component is MyComponent1.xml, the component ID is MyComponent1.
NOTE: The name attribute of the displayComponent tag specifies the component instance name.
<%@ taglib uri="/portal" prefix="ep" %> <html> <body> <b>DisplayComponent</b> <ep:displayComponent compID="MyComponent1" name="mycomp1"> <ep:param name="Parm1" value="Val1"/> <ep:param name="Parm2" value="Val2"/> <ep:param name="Parm3" value="Val3"/> </ep:displayComponent> </body> </html>
Tag library JAR files The Director tag libraries are distributed in the following JAR files:
TLD files Each of these JAR files contains a tag library descriptor (TLD) file in its META-INF directory. The TLD file is an XML file that describes the tags in the library. The Director tag libraries are described in the following TLD files:
For complete details on using the Director tag libraries, see the chapter on using the tag libraries in the Core Development Guide.
Director applications can include custom servlets. This version of Director supports servlets that conform to the Servlet 2.2 or 2.3 specification. Any servlets you create should conform to the specification supported by your target application server.
Where to put your servlets You should package your servlets in the WAR file that contains your Web application resources. Typically this WAR will be configured to use an internal resource set for Director resources. The servlets should be located in the WEB-INF/classes directory or in a JAR stored in the WEB-INF/lib directory within the WAR.
A custom servlet can access methods in the Director API. A servlet can use these methods to display PID pages and Director components, as well as to fire rules and access documents in the Content Management subsystem.
For example, to use a Director component in a servlet, you need to add some Java code that instructs the Presentation Manager to display the component. A servlet needs to provide all of the same information that is specified in the displayComponent tag (on a JSP page) or the s3-component tag (on a PID page). A servlet must specify a component ID, which provides the ID of the component, as well as a component instance name, which uniquely identifies the component on the page. In addition, if necessary, it can specify one or more custom parameters that alter the behavior of the component. A custom parameter is an arbitrary pairing of a name and a value that a particular component recognizes and uses.
The ID of a component is the name given to the XML file (without the extension) that describes the component. For example, if the XML file name for a component is MyComponent1.xml, the component ID is MyComponent1.
To use Director components in a servlet, you need to use the following interfaces:
You need to create the portal context, get a handle to the Presentation Manager, and call the getComponentData() method, as shown below:
/**
* Generated by Novell XSLT Code Generator, version 1.0.
* This generated source file may be freely modified.
*/
import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;
import java.util.*;
public class servlet extends HttpServlet
{
static final String CONTENT_TYPE = "text/html";
// Handle the HTTP GET request
public void doGet( HttpServletRequest request,
HttpServletResponse response )
throws ServletException, IOException
{
response.setContentType( CONTENT_TYPE );
PrintWriter out = response.getWriter();
try {
com.sssw.portal.api.EbiPortalContext ctx =
com.sssw.portal.factory.EboFactory.createPortalContext(
request, response, getServletContext() );
//ctx.setContextName( Constant.NAME );
com.sssw.portal.api.EbiPresentationManager pm =
com.sssw.portal.factory.EboFactory.getPresentationManager( ctx );
String s = pm.getComponentData( "Component1", ctx );
out.println( s );
}
catch( Exception e ) {
out.println( e );
}
}
// Handle the HTTP POST request
public void doPost( HttpServletRequest request,
HttpServletResponse response )
throws ServletException, IOException
{
response.setContentType( CONTENT_TYPE );
PrintWriter out = response.getWriter();
/** @todo Process the HTTP "POST" request here, and write the proper
response to the PrintWriter "out". */
out.println( "<html><head><title>servlet</title></head><body>" );
out.println( "<p>Servlet servlet has received an HTTP POST.</p>" );
out.println( "<p>The servlet generated this page in response to the
request.</p>" );
out.println( "</body></html>" );
}
}
A portal application can contain Portal Page ID (PID) pages. PID pages are pages that include s3-component tags and therefore require processing by the Presentation Manager. PID pages can contain HTML or XML.
Where to put your PID pages PID pages must be packaged in a resource set WAR, along with other resources required for the application. The PID pages must be located in the portal-page directory within the resource set.
Portal page descriptors Each portal page must have at least one XML descriptor. Each descriptor specifies the name of the HTML or XML file that provides content for the page, as well as additional parameters that control how the page will look and behave at runtime. The XML descriptor for a PID page must also be located in the portal-page directory within the resource set.
Here is an example of a descriptor for a portal page that provides HTML content. It specifies the name of the HTML file that provides content, as well as a display name and a description:
<portal-page> <display-name>Hello World</display-name> <description>Hello World Page</description> <file-name>HelloWorld.html</file-name> </portal-page>
Here is an example of a descriptor for a portal page that provides XML content. It specifies the name of the XML file as well as the name of a portal style that defines the XSL file that will be used for translation. This descriptor also specifies security role mappings for the page:
<portal-page> <display-name>Hello World</display-name> <description>Hello World Page</description> <category>UserPages</description> <mime-type>text/xml</mime-type> <style-name>HelloWorld</style-name> <file-name>HelloWorld.xml</file-name> <run-role-map> <role-name>manager</role-name> <role-name>administrator</role-name> </run-role-map> </portal-page>
The descriptor file for a portal page must have an XML extension. To indicate which portal page a descriptor applies to, you may want to include the file name of the portal page in the name of the descriptor. For example, if the portal page is stored in a file called HelloWorld.html, you might name the descriptor file HelloWorld.html.xml.
URLs for PID pages To display PID pages, the portal's base servlet breaks the request URL down into several components:
The host name identifies the server where the Director project was deployed.
The database name identifies the database where the Director project was deployed. This portion of the URL is only used when you deploy to a user database known to an exteNd application server. If you deploy to a SilverMaster database (for example, SilverMaster37) or to another application server, this portion of the URL is not used.
The EAR namespace specifies the namespace of the EAR. EAR namespacing applies only to EAR projects.
The base servlet mapping specifies the path to the base servlet. This portion of the URL is controlled by the mapping specified for the PortalControlServlet servlet in the web.xml for the WAR:
<servlet-mapping> <servlet-name>PortalControllerServlet</servlet-name> <url-pattern>/main/*</url-pattern> </servlet-mapping>
NOTE: You can change the base servlet mapping. However, if you do, you need to also change the PortalControllerServletPath context parameter. The value of this context parameter should match the servlet mapping, except that it should not include a preceding slash. By default, this context parameter has the value main.
The portal pages path specifies the path to portal pages in the WAR. This portion of the URL is controlled by the PortalPathPagesKey context parameter in the web.xml for the WAR:
<context-param> <param-name>PortalPathPagesKey</param-name> <param-value>pages</param-value> <description /> </context-param>
The PID page name identifies the requested item in the WAR. The PID page name specifies the name of the XML descriptor (without the XML extension). By convention, the name of the XML descriptor is often the same as the name of the portal page file. However, it need not be.
For example, suppose you want to access a portal page that has a descriptor file called HelloWorld.html.xml. The page is located in a WAR called SamplePortal.war, which is deployed in an EAR called acme. The EAR is deployed to a database called Director on a local exteNd application server. In this case, you could use the following URL to display the page:
http://localhost/Director/acme/SamplePortal/main/pages/HelloWorld.html
The page could also be accessed by using the following URL:
http://localhost/Director/acme/SamplePortal/main/pages?PID=HelloWorld.html
You can develop portal pages as typical HTML pages with graphics, tables, forms, and style sheets. You can use the text editor provided with Workbench, or any other HTML editor.
To write the HTML, you need to know how to include portal components on the page and create links to other portal pages and other resources on the application server. These are described next.
When you want to use a component in a portal page, you specify a special tag recognized by Director. You put the tag in the HTML where you want the component to insert its content. The tag specifies a component ID for a component.
The format for a component tag is:
<s3-component id="componentID" instance="instanceID" />
where arguments are as follows:
For example, to put a component in a table cell on your page, you would write HTML like this:
<td height="200"> <s3-component id="PhoneList" instance="MyPhoneList" /> </td>
A component tag can also have custom parameters that alter the behavior of the component. A custom parameter is an arbitrary pairing of a name and a value:
<td height="200"> <s3-component id="MyComponent" instance="mycomponentinstance" MYATTRIBUTE="myvalue" /> </td>
The code that implements the component must check for the value of the parameter (in this case MYATTRIBUTE) and modify its behavior accordingly.
XML is a practical way to render text-based pages with a simple layout. It is particularly useful when the page is made up of components.
You determine the XML elements you want to represent on your page. You also define an XSL style sheet for rendering the elements into HTML. The base servlet combines the two to display the portal page in the client browser.
You can use the same XSL for some or all of your portal pages to give your portal a consistent appearance. It's easy to tweak the appearance by changing the XSL, which affects all pages that use it, or by providing another XSL specification for any or all of the pages.
See
Personalizing Your Portal.
|
|
Portal Guide |
Copyright © 2000, 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.