| Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) Part Number B31074-05 |
|
|
View PDF |
| Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) Part Number B31074-05 |
|
|
View PDF |
This chapter provides an overview of OmniPortlet and explains the user interface elements associated with OmniPortlet. This chapter contains the following sections:
For troubleshooting information regarding OmniPortlet, see Appendix G, "Troubleshooting WebCenter Applications". For information about registering and configuring OmniPortlet, see Section 4.3.1, "Registering Portlet Producers".
OmniPortlet is a subcomponent of Oracle WebCenter Framework that enables developers to easily publish data from various data sources using a variety of layouts without writing any code. You can base an OmniPortlet on almost any kind of data source, such as a Web service, a SQL database, spreadsheet (character-separated values), XML, and even application data from an existing Web page.
Note:
You can find more information about developing different types of portlets in Chapter 14, "Understanding Portlets", and information about producers and other portlet technologies in Chapter 15, "Portlet Technologies Matrix".OmniPortlet enables the WebCenter application developer and component developer to do the following:
Display data from multiple sources (CSV, XML, Web service, SQL, and so on)
Sort the data to display
Format data using a variety of layouts (bulleted list, chart, HTML, and so on)
Use portlet parameters
Expose personalizable settings to page viewers
To display personalized data, you can refine the retrieved data by filtering the results returned from a data source, and parameterize the credential information used to access secure data. Out of the box, OmniPortlet provides the most common layout for portlets: tabular, chart, HTML, news, bulleted list, and form.
As described in Chapter 4, "Populating Pages", you can add an OmniPortlet to a JSP document created through Oracle JDeveloper. OmniPortlet is included in the WebCenter Preconfigured Oracle Containers for J2EE (OC4J) that is installed with Oracle JDeveloper. After you start the WebCenter Preconfigured OC4J, you can register the OmniPortlet producer by using the Oracle JDeveloper PDK-Java Producer Registration wizard. When this producer is registered, the portlets become available on the Oracle JDeveloper Component Palette. From here, you can drag-and-drop the portlets onto your *.jspx page.
Note:
For more information about:Registering the producer, see Section 4.3.1, "Registering Portlet Producers".
Installing, initializing, and stopping the WebCenter Preconfigured OC4J and pointing Oracle JDeveloper to it, see Section 3.2, "Using the Preconfigured OC4J".
Adding an instance of OmniPortlet to your page, see Section 4.3.2, "Adding Portlets to a Page".
Once you add an instance of OmniPortlet to your page, you must run your page to your browser, then click the Define link to start the OmniPortlet Wizard. For information about adding an instance of OmniPortlet to your page, see Section 4.3.2, "Adding Portlets to a Page".
Note:
When you add an instance of OmniPortlet onto your page in Oracle JDeveloper, open the Property Inspector for the portlet and ensure that the AllModesSharedScreen and RenderPortletInFrame properties are set as follows:AllModesSharedScreen is set to False to display the Customize and Personalize in full page size.
RenderPortletInFrame is set to True to display the OmniPortlet in its own iFrame in the View mode.
The OmniPortlet Wizard initially contains five steps. When you first define your OmniPortlet, you set the data source type, data source options, filter options, view options, and layout. When you've completed these steps of the wizard, you can reenter the wizard by clicking the Customize link for the portlet. When you reenter the wizard, you can change the definitions on the Source, Filter, View, and Layout tabs.
This section provides a high-level overview of the five tabs, which are described in Table 16-1. You can also find information in the online Help (accessible by clicking the Help link in the product), which describes the options on each tab.
Table 16-1 OmniPortlet Wizard and Customize Mode
| Step/Tab | Description |
|---|---|
|
|
Provides your data source options. Displays only in the initial definition of the portlet, and is not available when customizing the defaults of the portlet. |
|
|
Provides the options for the selected data source, such as the URL of the Web Service you want to use. You can change these options later when editing the defaults of the portlet. |
|
|
Provides sorting options at the WebCenter application level to enable you to refine your results. You can change these options later when editing the defaults of the portlet. |
|
|
Provides options for displaying portlet header and footer text, the layout style, and caching. You can change these options later when editing the defaults of the portlet. |
|
|
Provides detailed options for customizing the layout. You can change these options later when editing the defaults of the portlet. |
When you first start OmniPortlet, the Type step displays, which enables you to choose your data source (Figure 16-1). Out of the box, OmniPortlet supports the data sources shown in Table 16-2.
Figure 16-1 Type Tab of the OmniPortlet Wizard
Table 16-2 Supported Data Source Types
| Data Source Type | Description |
|---|---|
|
Spreadsheet |
Displays data from a text file containing character-separated values (CSV). |
|
SQL |
Displays data from a database using SQL. |
|
XML |
Displays data from an XML file. |
|
Web Service |
Displays data from a discrete business service that can be accessed over the Internet using standard protocols. |
|
Web Page |
Displays data based on existing Web content. |
After you complete the OmniPortlet Wizard and edit the defaults of the portlet, you cannot change the data source type.
After you've chosen your data source type, the Source step of the OmniPortlet Wizard displays. This step adapts to the data source you've chosen, enabling you to specify the options offered by that data source. The Source tab contains a Proxy Authentication section if the OmniPortlet producer has been configured to use a proxy server requiring authentication, and a Connection section where you can provide the necessary information for connecting to the data source.
This section contains information about the following two common areas on the Source tab:
Later, this section also describes the portion of the Source tab specific to each data source. The data sources available are as follows:
Note:
For more information about the Source tab options, click Help in the upper right corner of the page.OmniPortlet supports proxy authentication, including support for global proxy authentication and authentication for each user. You can specify whether all users will automatically log in using a user name and password you provide, each user will log in using an individual user name and password, or all users will log in using a specified user name and password. If the OmniPortlet producer has been set up to use proxy authentication that requires your login, then a Proxy Authentication section displays on the Source tab where you can enter this information.
The Proxy Authentication section only displays for the following data sources, which may require you to use a proxy server to access them:
CSV (character-separated values)
XML
Web Service
Web Page
For more information about configuring the OmniPortlet producer to use proxy authentication, see the online Help topic that displays when you click Help on the Edit Producers: OmniPortlet Producer page. If the OmniPortlet producer is configured to "Require login for all users," then each user must set his or her own login information as follows: - For page designers, set this in Customize: Source tab. - For page viewers, set this on the Personalize screen.
Notes:
To access the Customize: Source tab, click the Customize link for the portlet you want to modify.If you are using the Web Page data source, then the Proxy Authentication section displays in the Web Clipping Studio, after you have clicked the Select Web Page button on the Source tab.
For each data source except the Web Page data source, the Source step contains a Connection section, where you can define the connection information to access secured data. The Source step for all data sources include a Portlet Parameters section, where you can define the parameters for the portlet (Figure 16-2). You can then map the portlet parameters to the page-level parameters.
Figure 16-2 Source Tab: Connection and Portlet Parameters Section
To edit the connection information, click the Edit Connection button and fill out the information about the page shown in Figure 16-3. On this page, you can enter a name for the connection information, as well as the user name and password. For the SQL data source, you can enter more information to specify the driver you want to use to connect to the data source. For more information, see Section 16.2.2.4, "SQL".
Note:
For more information about the Connection section and the Edit Connection button, click Help on the Source tab of the OmniPortlet wizard.Spreadsheets are a common method of storing small data sets. OmniPortlet enables you to share spreadsheets by supporting character-separated values (CSV) as a data source. On the Source tab, you specify the location of the CSV file (Figure 16-4). If the file is located on a secure server, then you can specify the connection information in the Connection section described in Figure 16-2. You can also select the character set to use when WebCenter Suite reads the file, as well as the delimiter and text qualifier.
Note:
As the OmniPortlet producer exists and executes in a tier different from the WebCenter application and does not have access to the session information, you must expose CSV files as PUBLIC in order for OmniPortlet to access them.The relational database is the most common place to store data. OmniPortlet enables you to use standard JDBC drivers and provides out-of-the-box access to Oracle and any JDBC database. You can specify the driver type when you configure the connection information. Figure 16-5 shows the Source tab for a SQL data source.
You can use the DataDirect JDBC drivers to access other relational databases. To configure OmniPortlet to use these drivers, see Section B.2.2, "Configuring the OmniPortlet Producer to Access Other Relational Databases"
After the driver is installed, you'll notice it listed in the Driver Name list on the Connection dialog box on the Source tab, as shown in Figure 16-6.
Figure 16-6 Connection information about the SQL Source Tab
Note:
For more information about DataDirect drivers, see the Certification Matrix for Oracle Application Server and DataDirect JDBC (
http://www.oracle.com/technology/tech/java/oc4j/htdocs/datadirect-jdbc-certification.html) and the OC4J page on Oracle Technology Network (OTN) (http://www.oracle.com/technology/software/products/ias/htdocs/utilsoft.html).When you want to use one of the DataDirect drivers, you must use a unique connection string format: hostname:port, where hostname is the name of the server where the database is running, and port is the listening port of the database.
You can also make a call to Stored Procedures instead of SQL statement to add business logic to your data. You can create your package and stored procedure in your database and refer the stored procedure in OmniPortlet.
For example, you could do the following using the SCOTT sample schema:
Create a package and declare a ref cursor:
create or replace package emp_pack istype empcurr is ref cursor;end;
Define a stored procedure, for example following procedure accepts JOB as parameter and returns a ref cursor, where JOB Column in the scott.Emp table, its value can be CLERK, MANAGER, and so on.
create or replace procedure emp_proc(eset OUT emp_pack.empcurr, jname IN VARCHAR2) is sql_statement varchar2(200); begin sql_statement := 'select empno,ename,hiredate from emp where job = '''||jname||''' order by EMPNO,hiredate'; open eset for sql_statement; end;
Add the PL/SQL statements from steps 1 and 2 to a SQL file (for example, proc.sql) and save it to a directory.
Connect to the database using the following command:
sqlplus userid/password@Connection_String
Replace userid, password, and Connection_String the connection information to your database. You can find the connection string in the tnsnames.ora file within your ORACLE_HOME/network/admin directory.
Run the procedure:
@proc
Finally, create an OmniPortlet based on the SQL data source, enter the appropriate database connection information. In the SQL Statement box, enter the following code:
call emp_proc('CLERK')
You can access XML data sources across the intranet or Internet. On the Source tab, you can specify the URL of the XML file that contains your data as shown in Figure 16-7.
Next to the XML URL and the XSL Filter URL fields are Test buttons which you can use to validate your XML data source and the XSL filter.
The specified XML file can either be in tabular (ROWSET/ROW) structure, or you can provide an XML Style Sheet (XSL) to transform the data into the ROWSET/ROW structure. The following image shows an example of the ROWSET/ROW structure of an XML data source.
<TEAM>
<EMPLOYEE>
<DEPTNO>10</DEPTNO>
<ENAME>KING</ENAME>
<JOB>PRESIDENT</JOB>
<SAL>5000</SAL>
</EMPLOYEE>
<DEPTNO>20</DEPTNO>
<ENAME>SCOTT</ENAME>
<JOB>ANALYST</JOB>
<SAL>3000</SAL>
<EMPLOYEE>
</TEAM>
In this example, the <TEAM> tags delineate the rowset, and the <EMPLOYEE> tags delineate the rows.
Regardless of the format of the XML file, OmniPortlet automatically inspects the XML to determine the column names, which will then be used to define the layout. If you want to specify this information yourself, then you can supply a URL to an XML schema that describes the data.
Similar to the other data sources, you can also specify the connection information for this data source, if the XML file is located on a secured server protected by HTTP Basic Authentication.
Note:
As the OmniPortlet producer exists and executes in a tier different from the WebCenter application and does not have access to the session information, you must expose XML files as PUBLIC in order for OmniPortlet to access them.A Web Service is a discrete business service that can be programmatically accessed over the Internet using standard protocols, such as SOAP and HTTP. Web Services are not specific to platform and not specific to language specific, and are typically registered with a Web Service broker. When you find a Web Service you want to use, you must obtain the URL to the Web Service Description Language (WSDL) file that describes the Web Service and specifies the methods that can be called, the expected parameters, and a description of the returned data.
OmniPortlet supports both types of Web Services, Document and RPC (Remote Procedure Calls). After a WSDL document/file is supplied, it is parsed, and the available methods that can be called display on the Source tab.
Similar to the XML data source, OmniPortlet expects the Web Service data in ROWSET/ROW format, though you can also use an XSL file to transform the data. OmniPortlet inspects the WSDL document/file to determine the column names, though you may also specify an XML schema to describe the returned data set.
Figure 16-8 shows the Source tab for a sample Web service.
OmniPortlet enables you to use existing Web content as a source of data to publish information to your WebCenter application. It provides and renders clipped Web content as a data source.
The Web Page data source extends the scope offered by the Web Clipping Portlet to include scraping functionality. It also supports the following features:
Navigation through various login mechanisms, including form- and JavaScript-based submission, and HTTP Basic and Digest Authentication with cookie-based session management.
Fuzzy matching of clippings. If a Web clipping gets reordered within the source page or if its character font, size, or style changes, then it will still be identified correctly by the Web page data source and delivered as the portlet content.
Reuse of a wide range of Web content, including basic support of pages written with HTML 4.0.1 and JavaScript, retrieved through HTTP GET and POST (form submission).
All Web clipping definitions are stored persistently in the Oracle Metadata Services (MDS) by default. However, you can alternatively use an Oracle database. Using MDS does not require any changes in the configuration files. If you use an Oracle database as the Web Clipping repository, then you must update the provider.xml file.Any secure information, such as passwords, is stored in encrypted form, according to the DES (Data Encryption Standard), using Oracle Database encryption technology.
The Source tab of the OmniPortlet Wizard (Figure 16-9) enables you to start the Web Clipping Studio by clicking the Select Web Page button. Once you start the Web Clipping Studio, you can see the Oracle Application Server Web Clipping online Help.
Note:
For more information about using the Web Clipping Studio or creating a Web Clipping Portlet, see Chapter 17, "Creating Content-Based Portlets with Web Clipping".After you've selected the data source and specified the data source options, you can further refine your data by using OmniPortlet's filtering options. To use filtering efficiently, it is better to refine the data as much as possible at the data source level on the Source tab, then use the options on the Filter tab to streamline the data. For example, if you are using a SQL data source, then you could use a WHERE clause to return only specific data from the specified columns. In this case, you could skip the Filter tab and continue to the View page of the wizard. However, if there are no filtering options at the data source level, then you can use the options on the Filter tab to sort your data (Figure 16-10).
Once you've specified the data and sorted it, you can choose the view options and layout for your OmniPortlet. The View tab (Figure 16-11) enables you to add Header and Footer text, choose a Layout style that you can later refine on the Layout tab, and enable caching. You can choose from the following layouts:
Tabular
Chart
News
Bullet
Form
HTML
Note:
For more information about the different layout styles you can use with OmniPortlet, see the next section or click Help in the upper right corner of the page in the OmniPortlet Wizard.The Layout tab changes depending on the Layout Style you chose on the View tab, and enables you to further customize the appearance of your portlet. For example, OmniPortlet supports drill-down hyperlinks in the chart layout. That is, you can set up the chart so that when a user clicks on a specific part of the chart, an action occurs (for example, jump to another URL).
For the other layout styles, you can define each column to display in a specific format, such as plain text, HTML, an image, button, or field. For example, suppose you selected a data source that includes a URL to an image. To see this image, you can select Image for the display of this column. Each column can also be mapped to an action, similar to the behavior of chart hyperlinks.
The following layout styles are available with OmniPortlet:
Note:
As events are not currently supported, selecting an action when designing your layout may produce unexpected results.Once you've chosen the tabular style on the View tab, you can refine the layout on the Layout tab (Figure 16-12). Typically, you use the tabular layout if you have one or more columns of data that you want to display in a table. You can choose Plain to display all rows in the table without any background color, or Alternating to display a background color for every other row in the table.
Note:
You can control the background color of a portlet by using styles, as described in Chapter 9, "Defining and Applying Styles to Core Customizable Components".In the Column Layout section, you can choose which data columns to display in the portlet, then select a display format for the data. Here, you can set a column to display a hyperlink, so that a secondary Web page displays when the user clicks that column in the table. You can also specify whether the secondary Web page displays in a new window. Figure 16-13 shows an example of an OmniPortlet using a tabular format.
Figure 16-13 Example of an OmniPortlet Using a Tabular Layout
Note:
For more information about using the OmniPortlet Wizard, click the Help link in the upper right corner of the Layout tab.You can use the chart layout to display your data graphically, as a bar, pie, or line chart. On the Layout tab (Figure 16-14), you select the chart style and the column layout. When you choose the column layout, you can choose the groups, or columns on which the labels will be based. The category defines the values that will be used to create the chart legend, and the value determines the relative size of the bars, lines, or slices in the chart. You can also select whether the sections of the chart should point to a hyperlink, and whether the targeted information should display in a new window. Figure 16-15 shows an example of the Layout tab for a pie chart layout.
Note:
To group the information in the chart, you must group the information at the data level (for example, in your SQL query statement). Also, if numeric values in a data source contain formatted strings, commas, or currency (for example, $32,789.00), then they are considered to be text and ignored when the chart is generated. You should remove these formatting characters if you want them to be correctly read as numerical values.Figure 16-15 Example of the Layout Tab for a Pie Chart Layout
You can also define chart hyperlinks so that each bar, pie section, or line links to another Web page. For example, you can display a chart portlet and a report portlet on your page, then set up the chart hyperlink to display a row in the report that displays more detailed information about the selected data.
In Figure 16-16, you can see the results of the options selected on the Layout tab in the previous image. Below the chart, you can see that the category, which was Department on the Layout tab, is used for the legend.
Figure 16-16 Example of an OmniPortlet Using a Pie Chart Layout
You can use the news layout to display links to articles with brief descriptions for each. You can use this layout to publish information in standard XML formats, such as RDF (Resource Description Framework) or RSS (RDF Site Summary) to your page. In the Column Layout section (Figure 16-17), you can add a heading that displays at the top of the portlet. You can also add a logo, or use the scrolling layout so that the user can view all the information in the portlet as it moves vertically. Here, also, you can enter a URL so that another Web page displays when the user clicks on specific data in the portlet. You can also specify whether the secondary Web page displays in a new window.
Figure 16-18 shows an example OmniPortlet using a news layout.
Note:
The News Layout Scroll type in OmniPortlet is supported on Microsoft Internet Explorer and Netscape 7.0.Figure 16-18 Example of an OmniPortlet Using a News Layout
Note:
For more information about using the OmniPortlet Wizard, click the Help link in the upper right corner of the Layout tab.You can use the bullet layout to display your data in a bulleted list. The Layout tab (Figure 16-19) provides a variety of different bullet and numbered bullet styles. In the Column Layout section, you can choose how the columns will display in the portlet, as well as whether a second Web page will display when the user clicks that column. You can also specify whether the second Web page displays in a new window.
Figure 16-20 shows an example of an OmniPortlet using a bullet layout.
Figure 16-20 Example of an OmniPortlet Using a Bullet Layout
Note:
For more information about using the OmniPortlet Wizard, click the Help link in the upper right corner of the Layout tab.You can use the form layout (Figure 16-21) if you have data you want to display as labels or default values in a form, such as Name: <name>. You can then use portlet parameters to pass data to the selected row.
You can also specify whether to display the target of a URL in a new window (Figure 16-22). Figure 16-23 shows an example of an OmniPortlet using a Form layout.
Figure 16-22 Open In New Window Check Box
Figure 16-23 Example of an OmniPortlet Using a Form Layout
Note:
For more information about using the OmniPortlet Wizard, click the Help link in the upper right corner of the Layout tab.You can use the HTML layout to create a customized look and feel for your portlet by choosing from either a built-in HTML layout and modifying the code, or by creating a new layout from scratch. You can hand-code your own HTML or JavaScript based on data columns that OmniPortlet has retrieved based on the selected data source (Figure 16-24). By coding your own HTML and JavaScript, you have full control over the appearance and develop a rich interface for your portlet.
For more information about using the fields on this tab, click the Help button in the wizard. For an example of using JavaScript in the HTML layout, choose the Sortable Table layout from the Quick Start list on this tab.
Note:
The maximum number of characters you can enter in each of the sections (Heading, Repeating, and Footer) is 30,000 (30k).Figure 16-25 shows an example of an OmniPortlet using the HTML layout.
Figure 16-25 Example of an OmniPortlet Using the HTML Layout
After you have created your OmniPortlet and returned to your application, you can click the Customize link for your portlet to change the portlet options if required. You will notice that, in the Customize mode, there are tabs that correspond to the different steps in the OmniPortlet Wizard (except for the Type step) to directly access the different options.
When you edit an OmniPortlet using the Customize mode, keep in mind the following notes:
Any modifications you make to your portlet using the Customize mode apply to all users, regardless of the current session language and the locale of the user's browser.
You can personalize the portlet at run time by clicking the Personalize link on the portlet. Personalizing the portlet creates a copy of the personalization object. As all properties are duplicated, subsequently modifying the portlet through the Customize mode does not affect the personalized version of the portlet. To ensure the latest Customize changes are made to the portlet, you must click Personalize again (after you have made the modifications in the Customize mode), then select the Reset to Defaults option.
By default, the OmniPortlet producer uses the file-based Preference Store to store the personalization object, which stores the object in a file system in the middle-tier. If you decide to deploy OmniPortlet in a multiple middle-tier environment, then you must configure the File Preference Store to a shared file system, or use the Database Preference Store (DBPreferenceStore). To do so, follow the steps in Section B.2.3, "Configure Portal Tools and Web Producers (Optional)".
You can define up to five portlet parameters for an OmniPortlet. You can define parameters in the following screens:
On the Source tab of the wizard when you define the OmniPortlet
On the Source tab when you select Customize for the OmniPortlet
Figure 16-26 shows the Portlet Parameters section on the Source tab.
Figure 16-26 Source Tab: Portlet Parameters Section
Note:
You can learn more about portlet parameters in the online Help, which you can access by clicking the Help link on the Source tab in the OmniPortlet Wizard. The online Help describes portlet parameters in detail, and how to set them up for your OmniPortlet.Once you have set up portlet parameters in your OmniPortlet, you can contextually map the portlet to other portlets or components on a page. For more information about doing so, see Section 4.5, "Contextually Linking Components".
In this chapter, you learned about OmniPortlet and its capabilities. You also learned about using parameters. You can find more information about using the various tools in OmniPortlet by clicking the Help link on each of the pages in the wizard.
Note:
For more information about configuring OmniPortlet, see Appendix B, "OmniPortlet Configuration Tips".
