Oracle® Access Manager Customization Guide 10g (10.1.4.0.1) Part Number B25345-01 |
|
|
View PDF |
The Identity System combines XSL (eXtensible Style Language) stylesheets and XML (eXtensible Markup Language) data to dynamically create almost all of the pages presented to its users. This capability, called PresentationXML, provides Oracle Access Manager developers with a great deal of design flexibility and avoids the necessity of providing many pages of static HTML content along with the product.
Within the bounds described in this chapter, you can use this feature yourself to customize Identity System user application presentation to suit your own needs. For example, you can:
Apply your organization's color schemes and other graphical style elements such as fonts, button images, and logos, to Oracle Access Manager pages.
Add, modify, or remove particular functions on an Identity System page.
Add hidden information which could be used by the Identity Event Plug-in API (see the Oracle Access Manager Deployment Guide).
This chapter tells you how to use PresentationXML and includes the following topics:
PresentationXML Libraries—Provides a listing and description of some major parts of the full library of PresentationXML components.
Customizing Oracle Access Manager—Provides an outline of one method for doing customization.
Customizing the Identity System Pages—Gives an example you can complete to gain first-hand experience with customizing Oracle Access Manager.
Note: Prior experience with XSL and XML is not essential to using PresentationXML. However, you will need to learn and understand them as you delve into more complex kinds of changes. Some reference sites and brief syntax introduction are provided in Appendix A, "XML Background". |
Note: Prior experience with XSL and XML is not essential to using PresentationXML. However, you will need to learn and understand them as you delve into more complex kinds of changes. Some reference sites and brief syntax introduction are provided in Appendix A, "XML Background". |
The System Administration Console always uses the default, Classic Style.
This section describes how standard PresentationXML operates, introduces some parameters that can be used to control its output, and describes a useful alternate mode of operation. The terms you will see include:
Stylesheet: This term identifies XSL stylesheets that describe how data sent over the Web is to be presented to the user.
Base Stylesheet: This term refers to several Identity System stylesheets that provide a foundation for other stylesheets:
basic.xsl
font.xsl
searchform.xsl
navbar.xsl
title.xsl
Wrapper: This term identifies an XSL stylesheet file that contains only XSL include statements with pointers to other files.
This discussion outlines the encoding schemes you will see in XSL stylesheet files, and what to specify if you customize these files.
XML must start with the following string:
<?xml version="1.0"?>
10g Release 3 (10.1.4) supports two encoding formats for requests: ISO-8859-1 (Latin-1) and UTF-8. The response, however, will be in UTF-8 encoding only.
Within this required string you can use a tag to select an encoding specification.
With new 10g Release 3 (10.1.4) installations, use the UTF-8 encoding tag (encoding="UTF-8"
), as follows.
<?xml version="1.0" encoding="UTF-8" ?>
For backward compatibility with older plug-ins in an upgraded environment, use the Latin-1 encoding tag (encoding="ISO-8859-1"
). For example:
<?xml version="1.0" encoding="ISO-8859-1" ?>
ISO-8859-1 Encoding: For pure English text, there is no difference between ISO-8859-1 encoding and UTF-8 encoding. For this reason, the encoding scheme for English language XSL files remains ISO-8859-1 in most if not all wrapper files in the \lang\langtag\style0 directory.
The following example shows an XSL stylesheet wrapper (style.xsl), which is the same in all language directories: English (\lang\en-us), German (\lang\de-de), Japanese (\lang\ja-jp) and so on. The only difference in these files is the language designation specified by the langtag item in the last line of this example, which will differ from country to country (language to language):
\IdentityServer_install_dir\identity\oblix\lang\langtag\style0\style.xsl
<?xml version="1.0" encoding="ISO-8859-1" ?> - <!-- Copyright (c) 1996-2005, Oracle All Rights Reserved. --> - <xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:oblix="http://www.oblix.com/"> <xsl:variable name="styleName">style0/</xsl:variable> <xsl:variable name="localeName">langtag</xsl:variable>
...
UTF-8 Encoding: To enable multibyte character support, you can explicitly define the encoding to be UTF-8. Without the encoding string, the default encoding specification is UTF-8. In global stylesheets, for example, there is no encoding specified and the default is UTF-8 as follows (\IdentityServer_install_dir\\identity\oblix\lang\shared\style.xsl):
<?xml version="1.0" <!-- Copyright (c) 1996-2005, Oracle All Rights Reserved. --> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/"> <xsl:variable name="styleName">style0</xsl:variable> <xsl:variable name="localeName">en-us</xsl:variable> <xsl:variable name="gifPathName">../../../lang/<xsl:value-of select="$localeName"/>/<xsl:value-of select="$styleName"/></xsl:variable> <xsl:variable name="jsPathName">../../../lang/shared</xsl:variable> </xsl:stylesheet>
Note: When customizing XML and XSL files, you can choose either encoding="ISO-8859-1" or encoding="UTF-8". In either case, the Oracle Access Manager XML parser reads the encoding tag in the file for correct processing. |
The diagram on the next page shows the default data flow for PresentationXML. This default process, called server-side processing, generates HTML and presents it to the browser. The following steps are performed.
Process overview: Server-side processing
The browser sends a request to the URL of a Web server that includes the WebPass plug-in.
The full URL contains the location of the Web server and implicitly the application, such as the Group Manager, that is expected to service the request. The URL also usually includes information telling the application what task to perform and providing parameters that direct the task. (See more on the full syntax for the URL in "Identity System Applications".)
WebPass takes the request, makes a few minor changes to it, and passes it to the Identity Server.
The Identity Server passes the request to the appropriate application. (For the sake of clarity, the diagram shows the application as if it were a separate entity, but it is actually a dynamically loaded part of the Identity Server.)
The application processes the request and creates an XML file named OutputXML.
OutputXML contains information that will appear as part of the final HTML. The application also opens its registration file to get the name of the base XSL stylesheet that applies to the request that it has just satisfied, as illustrated in Figure 2-1.
The OutputXML and the name of the base stylesheet are returned to the Identity Server.
The Identity Server reads the text of the base stylesheet from the library. This text usually includes references to other stylesheets, which are used in common by many different types of requests. For each reference, the Identity Server reads the additional text from the stylesheet library and inserts it in-line in place of the reference, making one large stylesheet.
An XSLT (XSL transformer) application is part of the Identity Server. The XSLT parses and interprets the stylesheet and combines it with the OutputXML to create HTML. The OutputXML content provides a basis for the decisions that are made as the stylesheet is interpreted and also provides data to be included in the HTML.
When the entire stylesheet has been processed, the resulting HTML is sent to WebPass, which returns it to the browser.
The browser uses WebPass to obtain GIF images and JavaScripts as needed.
You can append any of three parameters, format, xsl, and style, to the URL to shape the way the XSLT works with the OutPutXML and the stylesheets.
The format parameter can be used to control the way in which the Identity Server combines the OutputXML and the stylesheet before the resulting information is passed to the browser, if this is allowed by the setting of a certain parameter in the globalparams.xml parameter file. (See Table B-9 for details.) The Identity Server checks the value that was provided for the outputFormat parameter in this file. The parameter must be set to default in the parameter file to enable use of the format parameter here in the PresentationXML URL.
The format parameter takes one of three values
Default: If the parameter is not included in the URL XSLT processing is done at
format=xmlnoxsl: The Identity Server returns the Output XML without doing XSLT processing; that is, the XSL stylesheet is not applied. This is a good way to generate the OutputXML. If you do this, and want to capture the result, save the displayed data as XML (if your browser supports this). The true OutputXML contains escaped characters that will be lost if you save the displayed data as a text file.
Note: If the same CGI is used to handle different functionality, just appending "&format=xmlnoxsl" to the URL would result in executing the default functionality of a given CGI. |
If the same CGI is used to handle different functionality, you need a way to re-submit the form request with "&format=xmlnoxsl" as part of the action. This can be achieved using the following methods.
Method 1: Append "&format=xmlnoxsl" to the form action within the relevant .xsl stylesheets. While this may seem straight-forward enough, be aware that you are making changes to a stylesheet and this could have unintended consequences. After making the change, you need to either restart the Identity Server or update the globalparams.xml file to disable stylesheet caching (for example, set stylesheet caching to 1) and allow stylesheet dynamic-change updates.
Method 2: Rewrite the POST request as a GET request, and add &format=xmlnoxsl. One way of rewriting the POST request as a GET request is to use a portal insert. See "Customizing Portal Inserts" for details.
It is not always possible to tell directly what parameters are being passed to the POST request.
Sometimes the action is a JavaScript that rewrites the form parameters before the form request gets submitted. In such instances, you may want to run a packet sniffer to capture the POST request as it is leaving the browser. Alternatively, you can enable debugging on the Identity Server and look at the request data. However, you may have to sift through a certain amount of non-relevant data. You then recreate the POST request as a GET request because it is easier to submit as one URL. In some rare cases, the POST data is too long and does not fit as a GET request, so you can write an HTML static form and manually fill-in the data from the POST request captured with the sniffer or from the Oracle Access Manager debug log.
Note: Oracle has found certain packet sniffers useful. For example, daSniff available athttp://demosten.com/dasniff offers a command-line interface and requires the WinPcap libraryavailable at http://netgroup-serv.polito.it/winpcap . |
format=xml: The Identity Server returns the Output XML, with the name of the base XSL stylesheet embedded as an XML element. For this to be useful, the browser must be able to do its own XSLT processing. In that case the browser sends requests to WebPass for the content of included stylesheets, and WebPass gets them directly from the appropriate library.
The only browser currently able to do its own XSLT processing is Microsoft's Internet Explorer (IE). IE Versions 5.5 and later are compatible with PresentationXML.
Earlier versions of IE use an earlier proposed version of XSLT, based on a working draft from 1998. This is inconsistent with the current version of XSLT, which Oracle Access Manager follows. To use the format=xml
option with the earlier versions of IE, you must either rewrite the XSL stylesheet to be consistent with the earlier draft version or download Microsoft's patch to its XSLT processor.
See also: See Appendix A, "XML Background" for a discussion of how to download and install the patch. |
The xsl parameter determines which XSL stylesheet is to be combined with the OutPutXML. It can take either of two values:
Default: If the parameter is not included in the URL, the default is to apply the XSL stylesheet specified in the registration file.
xsl=stylesheet_name: Use the specified stylesheet as the base stylesheet, in place of the one specified in the Registration File.
The style parameter indicates which style directory in the library to get the base stylesheet from. (For an explanation of styles, see "Styles".) Once the style parameter has been used in the URL, the style you chose is implicitly included in all further requests in the session for that particular browser.
Default: If the parameter is not included in the URL, the default is to either: get the base stylesheet from the style0 directory (if the style parameter has not been previously used), or continue to get the base stylesheet from the style directory specified by a previous use of the style parameter).
style=styledirectoryname: Get the base stylesheet from the specified style directory, and continue to do so for the rest of the session with this browser.
Note: Administrators can create new style directories and set them as the default style. In the current discussion,style0 stands for the default style directory. |
The diagram on the following page shows the major alternative method for using PresentationXML. This method is called client-side processing, because it presumes that the browser will generate its own HTML, given the OutPutXML and the base stylesheet. To set this up, you use the format=xml parameter as discussed earlier. In this case, the only responsibility of the Identity Server is to pass the OutPutXML, with the name of the base stylesheet embedded, through WebPass back to the browser. The browser then sends requests to WebPass for various library components as it needs them.
Process overview: Client-side processing
The browser sends a request to the Web server, as in server-side processing.
WebPass takes the request, makes a few minor changes to it, and passes it to the Identity Server, as before.
The Identity Server passes the request to the appropriate application, as before.
The application processes the request, creates an OutPutXML file, and retrieves the base stylesheet, as before.
The OutputXML and base stylesheet are returned to the Identity Server, as before.
However, the Identity Server does no processing of the OutPutXML. Instead, it embeds the base stylesheet name into the OutPutXML and sends the result to Webpass, which passes it the browser.
The browser then makes requests to the Web server, as needed, for the referenced stylesheets, images and JavaScripts, as illustrated in Figure 2-2.
For the sake of efficiency, the Identity System maintains a cache of stylesheets, converted to a binary format. Stylesheets can be changed while the Identity System is running, but will need to be forced into this cache in order to take effect. One way to do this is to stop and start the Identity Server.
Another way is to use the XSL stylesheet control parameters provided (page 211) in the globalparams.xml parameter file:
Identity_install_dir\identity\oblix\apps\common\bin\globalparams.xml
where Identity_install_dir
is the directory where the Identity Server is installed.
There are two of these:
XSLStylesheetLiveUpdate: The default value for this parameter is false, which means, if the stylesheet is cached, the Identity System uses the cached binary version regardless of any changes to the original file. In a production environment, this parameter should be set to false. Setting it to true causes Oracle Access Manager to compare file stamps to see if the stylesheet has been modified in between requests. This is not desirable in a production system because it is an unnecessary overhead.
Changing the value to true causes a check of the timestamp of the text version of the file against the timestamp for the cached version. If the cached version is older, the text file is converted to binary and replaces the older version in the cache. Note, however, that this works only for base stylesheets.
XSLStylesheetCacheSize: Default value for this parameter is 200. In a development environment, you can change the value to 1 so that only one stylesheet can be cached (0 is not a legal value). Go forward one page, then return to the one you are testing. This works for stylesheets at all levels.
Recommendation: In a production environment, the XSLStylesheetCacheSize parameter should be at least equal to or greater than the number of base stylesheets. The value of this should be greater than 200. To optimize performance, you should also set the XSLStyleSheetLiveUpdate parameter to false.
To prepare for customizing the PresentationXML style sheets, you need to be able to preview the effect that updated style sheets will have on the user interface. To be able to preview your changes, you must set up an XML editor and create local versions of Identity application XML files. This section discusses these topics, including a discussion of setting up the XMLSpy editor. You can use XMLSpy to test changes that you make to the style sheets. XMLSpy is an XML development environment that enables you to transform XML documents according to definitions in XSL style sheets.
The procedures in this section are appropriate for users who are new to XMLSpy. If you have more experience with it and with PresentationXML, you can modify the steps as needed.
The following task overview summarizes the steps to generating the XSL files that you want to customize.
Task overview: Setting up your environment to test style sheet customizations
Make local copies of your PresentationXML folders and add them to an XML editing environment.
See "To configure PresentationXML folders in XMLSpy" for details.
Configure PresentationXML image folders.
See "To configure IdentityXML image folders for local testing" for details.
Import the XML that you want to customize using the style sheets.
See "To import an Identity System XML file to work with its respective XSL style sheet" for details.
Transform the XML file with the XSL style sheet.
See "To transform the XML file to XSL" for details.
To configure PresentationXML folders in XMLSpy
Create a folder named Presentation XML, for example:
c:\PresentationXML
This is your working folder. You can copy the XSL for the Identity Server and WebPass, and the images into this folder.
Create two sub-folders under the one that you created in the previous step named "identity" and "webcomponent".
Copy the Identity style sheets folder from the Web server into the "identity" folder.
Copy from:
Identity_Server_install_dir
\identity\oblix\lang
To:
c:\PresentationXML\identity\
The resulting directory structure should be similar to the following:
C:\PresentationXML identity lang en-us\. . . shared\. . . webcomponent
For the WebPass stylesheets, copy the entire WebComponent style sheets folder, with its subdirectories, from the Web server where WebPass is installed into the webcomponent folder that you created, as follows:
Copy from:
WebPass_install_dir
\webcomponent\oblix\lang
To:
C:\PresentationXML\webcomponent\
The resulting directory structure should be similar to the following:
C:\PresentationXML identity lang en-us\. . . shared\. . . webcomponent lang en-us\. . . shared\. . .
Launch XMLSpy.
To start a new project, click Project, then click New Project.
In the XMLSpy Project pane, right-click the XSL Files folder and select Add External Folder.
Browse to the following location:
C:\PresentationXML\identity
Select the identity folder and click OK.
Repeat the previous step for the webcomponent folder.
To configure IdentityXML image folders for local testing
In XMLSpy, modify the path to the images and javascript files.
This is required because there is a common reference to all images when running on a Web server, but not on your local drive.
In XMLSpy or a text editor, open the following style.xsl file:
C:\PresentationXML\identity\lang\en-us\style0
Change the gifPathName on line 8 as follows:
From:
../../../lang
To:
C:\PresentationXML\webcomponent\lang\shared
Change the jsPathName in line 9 as follows:
From:
../../../lang/shared
To:
C:\PresentationXML\webcomponent\lang\shared
To import an Identity System XML file to work with its respective XSL style sheet
Go to the Identity System function that you want to customize.
For example in the Identity System, click User Manager, then click My Identity.
Append the following to the URL string used for this page:
&format=xmlnoxsy
Press Enter or Go.
As illustrated in Figure 2-3, the profile page is shown as raw XML.
In your browser, save this information as a file by clicking File, then clicking Save As and providing a file name, for example, viewProfile.xml.
Create a folder for storing the XML files that you created using the &format=xmlnoxsl parameter, for example:
C:\PresentationXML\xml
In XMLSpy, to add the XML folder that you created in the previous step, right-click the XML Files folder, click Add External Folder, browse for the XML folder, and click OK.
In XMLSpy, expand the XML Files folder in the Project pane and double-click the file that you want to transform.
The file contents appear in the right pane.
To transform the XML file to XSL
In XMLSpy, click XSL/XQuery, then click XSL Transformation.
Browse the XSL style sheets, for example, to transform the My Identity page, you would navigate to the following:
C:\PresentationXML\identity\lang\en-us\style0\usc_profile.xsl
Click Open.
Click OK.
After a minute, the HTML output based on the transformation of the XML and XSL appears.
Modify the XSL file as described in the following sections and test the changes in XMLSpy.
This section describes the Identity System components that work together to create PresentationXML. These components are:
XSL Transformer: In addition to transferring data between WebPass and the applications, the Identity Server is usually responsible for transforming the OutPutXML (using the stylesheet as a guide) into HTML for use by the browser. To accomplish this, the Identity Server contains a built-in XSL Transformer. See "XSL Transformer" for details.
Applications: The functional entities within the Identity Server, such as the User Manager or Lost Password Management, that handle the logic specific to each request. See "Identity System Applications" for details.
URLs: The location information, and other parameters, that the browser provides in order to make a request through WebPass to reach a specific application. See "URLs" for details.
Output XML: The stream of XML data created by each Identity System application. This can be captured as a file. It contains the information to be shown on the requested page. See "OutPutXML" for details.
XML Schemas: Files that describe the type and hierarchy of data that appears in the OutPutXML. See "XML Schemas" for details.
Registration files: Files that specify which stylesheets to use and which XML schema file describes the OutPutXML. See "Registration Files" for details.
JavaScripts: JavaScript applications which perform specialized tasks. Pointers to these are provided within the HTML. See "JavaScripts" for details.
Styles: Collections of data that support the generation of the HTML for the page. For each application, the data includes:
Stylesheets: Files containing XSL instructions which tell the XSL transformer how to use the information provided in the OutPutXML. See "XSL Stylesheet Content" for details.
Images: Small graphic files referenced in the HTML, which are combined to make the final GUI presentation. See "Images" for details.
The Identity Server contains a built in XSL Transformer. The Transformer follows the logic provided in an XSL stylesheet and creates a file of text following an HTML format. The Transformer uses the content of the OutPutXML to determine branches at decision points in its logic and to get content for data to be included in the HTML.
PresentationXML supports six applications, which are dynamically loaded and then executed from within the Identity Server. The following table lists the applications and shows the name for each application. The browser provides a URL as part of its request to the Identity Server and the application name appears as a string within the URL. The application name also appears as a directory name, under which the PresentationXML data for the particular application can be found (see "Directory Structure" for details). Descriptions of each application and details for using each one are provided in the Oracle Access Manager Introduction.
There is an additional legal value which is used in URLs for activities that are common across applications:
Application | Application Name |
---|---|
Resources used across applications | common |
URLs that the browser provides to the Identity Server are of two basic kinds. First is the URL for the first page of each application, the one you arrive at after logging in. An example is the front page URL for User Manager:
http://www.domain.com/identity/oblix/apps/userservcenter/bin/ userservcenter.cgi
This can be divided into several parts. The first part is:
http://www.domain.com/
which is the location of the server site to which the Identity Server has been added as a plug-in. The second part:
http://www.domain.com/identity/oblix/
tells the server site that you want to work with the Identity Server. The third part is:
apps/userservcenter/bin/userservcenter.cgi
which tells the Identity server which of its applications, in this case the User Manager, you want to work with.
Formally, as discussed in the specification Internet RFC 2396- Uniform Resource Identifiers (URI): Generic Syntax, the following string:
identity/oblix/apps/userservcenter/bin/userservcenter.cgi
is a path to an application that can be executed.
Table 2-0 shows the path to the first page URL for each application:
Table 2-1 URL to the First Page for Each Application
Application | Application Front Page URL |
---|---|
|
|
|
|
|
|
|
|
|
|
|
The front page in turn contains links to other pages in the application. The URL for such a link could resemble the following:
http://www.domain.com/identity/oblix/ apps/ userservcenter/bin/userservcenter.cgi ?program=view &uid=cn%3DJohn%20Smith%2C%20ou%3DCorporate %2C%20ou%3DCompany%2C%20c%3DUS &tab_id=Employees
This an extension of the content of the front page URL. The information that locates the server and specifies the application to use are as they were before. Added are several parameters, set off by the ? and & delimiters.
For PresentationXML, the most significant parameter is program, which identifies the purpose of the requested page. The program name serves as a lookup index in a registration file for each application.
See also: See Chapter 3, "Customizing Portal Inserts" for URL parameters.See "Registration Files" for information on registration files. |
OutPutXML is a structured stream of information which contains the content of a page to be created by using Presentation XML. The arrangement of this content and the choice as to how much of it will appear on the final page is determined by the stylesheet that is applied to it.
Each application generates an OutPutXML stream matching the task that it is performing. The content of this stream varies significantly with the directory content that the application is working with.
The detailed content of the OutPutXML is therefore not predictable. However, it is possible to predict the kinds of data that an OutPutXML stream will contain, because this data conforms to XML schemas which Oracle Access Manager follows for each application.
Given the application and the program name, you can locate the corresponding schema file name in the application's registration file.
The OutPutXML information generated by each program within each Identity System application is hard-coded and is not directly changeable by users. The content of the OutPutXML is not controlled by the content of the XML schema file. The file is provided only as a developer's aid, to help you design XSL stylesheets to work with the OutPutXML. XML schema files follow a standard developed by the World Wide Web Consortium. See "XML Schema" for the standard, and an introduction to XML syntax.
Note: XML schema files do not have any effect on the PresentationXML and are located only on WebPass. Oracle recommends that you not change any of the XML schema files. |
Here is an example XML schema file, the complete usc_profile.xsd file, located in WebPass_install_dir\identity\oblix\WebServices\XMLSchema\usc_profile.xsd
:
<?xml version="1.0" encoding="UTF-8"?> <!-- edited with XMLSPY v5 rel. 3 U (http://www.xmlspy.com) by zzz (zzz) --> <xsd:schema targetNamespace="http://www.oblix.com/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.oblix.com/" elementFormDefault="qualified"> <xsd:include schemaLocation="component_profile.xsd"/> </xsd:schema>
The line in bold beginning with xsd:include indicates that there is more information to be included in-line in this schema definition, in the file at:
../..//XMLSchema/component_profile.xsd.
The complete content of the component_profile.xsd file follows. You will notice that this file includes pointers to four other schema files, such as navbar.xsd:
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema targetNamespace="http://www.oblix.com/" xmlns:xsd="http:// www.w3.org/2001/XMLSchema" xmlns="http://www.oblix.com/" elementFormDefault="qualified"> <xsd:include schemaLocation="navbar.xsd"/> <xsd:include schemaLocation="searchform.xsd"/> <xsd:include schemaLocation="component_panel.xsd"/> <xsd:include schemaLocation="component_basic.xsd"/> <xsd:element name="ObProfile"> <xsd:complexType> <xsd:sequence> <xsd:element ref="ObPanel" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="ObHeaderPanel" minOccurs="0"/> <xsd:element ref="ObRequestInfo" minOccurs="0"/> <xsd:element ref="ObScripts" minOccurs="0"/> <xsd:element ref="ObForm" minOccurs="0"/> <xsd:element ref="ObDisplay" minOccurs="0"/> <xsd:element ref="ObTextMessage" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="ObSelectorInfoForm" minOccurs="0"/> <xsd:element ref="ObButton" minOccurs="0" maxOccurs="unbounded"/> <xsd:element ref="ObStatus" minOccurs="0"/> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="Oblix"> <xsd:complexType> <xsd:sequence> <xsd:choice> <xsd:element ref="ObProfile"/> <xsd:element ref="ObError"/> </xsd:choice> <xsd:element ref="ObNavbar" minOccurs="0"/> <xsd:element ref="ObSearchForm" minOccurs="0"/> <xsd:element ref="ObApplicationFunc" minOccurs="0"/> <xsd:element ref="ObStatus" minOccurs="0"/> </xsd:sequence> <xsd:attribute name="oblang" type="xsd:string"/> </xsd:complexType> </xsd:element> </xsd:schema>
This file is representative of most of the XML schema files in that:
It begins with a set of included XML schemas, ones that are used in common across several applications.
The lines starting with <xsd:element name="ObProfile">
and ending with </xsd:element>
define an element called ObProfile.
The lines in between, starting with <xsd:element ref=
indicate that the ObProfile element contains the nested elements ObPanel
, ObHeaderPanel
, and so on.
Note: ObProfile in turn is referenced as part of the Oblix element, which is the root element of the entire Oracle Access Manager schema. The root element will be the starting point for the application of the XSL stylesheet. |
XML schema files do not have any effect on the PresentationXML and are located only on WebPass.
The following are some of the most often used schema files:
navbar.xsd: Defines the Navigation Bar, which is the top two lines of each page, including the application name, help and logout buttons, and the various tabs to select other applications or modules within the application.
searchform.xsd: Defines the Search Form line, which is the row of graphics shown on some pages, that starts with the graphic labeled search. This row may have other rows beneath it.
component_panel.xsd: Defines the content for profiles, the sets of descriptive information for users, groups or organizations.
component_basic.xsd: Defines many of the lowest level elements, and includes displaytype.xsd and error.xsd.
displaytype.xsd: Defines formatting for each of the Identity System display types.
error.xsd: Defines the ObError element.
Each of these files contains other nested elements, and so on. For easy reference, tables giving the names of the most commonly used schema files, the names of the elements contained within them, and a brief description of what each element is, are provided in the "XML Schema Elements Library".
Note: The OutPutXML information generated by each program within each Identity System application is hard-coded and is not directly changeable by users. The content of the OutPutXML is not controlled by the content of the XML schema file. The file is provided only as a developer's aid, to help you design XSL stylesheets to work with the OutPutXML. Users should not change any of the XML schema files. |
Each of the Identity System applications has associated with it a unique registration file. This is a text file holding information arranged as a series of XML elements. Using the ObProgram name that appears in the URL for a lookup index, the specific Identity application searches its registration file to get the name of the base stylesheet that is to be applied to the OutPutXML. As an aid to the developer, the registration file also holds the name of the XML schema that describes the OutPutXML for the program.
Table 2-0 shows the path to the registration file for each application.
Table 2-2 Path to the Registration File for Each Application
Application | Registration File Location |
---|---|
Identity_install_dir\identity\oblix\apps\ groupservcenter\bin\groupservcenterreg.xml |
|
Identity_install_dir\identity\oblix\apps\ objservcenter\bin\objservcenterreg.xml |
|
Identity_install_dir\identity\oblix\apps\ userservcenter\bin\userservcenterreg.xml |
|
Identity_install_dir\identity\oblix\apps\lost_pwd_mgmt\bin\lostpwdmgmtreg.xml |
|
Identity_install_dir\identity\oblix\apps\ querybuilder\bin\querybuilderreg.xml |
|
Identity_install_dir\identity\oblix\apps\selector\ bin\selectorreg.xml |
The main applications also frequently call logic from the common resource applications. When this happens the application looks for the appropriate stylesheet in the common registration file:
Application | Application Name |
---|---|
Common resources | Identity_install_dir\identity\oblix\common\bin\ oblixbasereg.xml |
Registration files have the following general content. In the following example, key variable values within each registration file are indicated in italic text. Structural elements in the following example appear in bold.
<?xml version="1.0"?> <ObProgramRegistry> <ObApplication name="application_name"> <ObProgram name="a_program_name"> <ObStyleSheet name="stylesheetname.xsl"/> <ObSchema name="Its_XML_schema_name.xsd"/> </ObProgram> <ObProgram name="a_program_name"> <ObButton name="a_button_name"/> <ObButton name="another_button_name"/> <ObButton name="yet_another_button_name"/> <ObButton name="maybe_more_button_names"/> <ObStyleSheet name="stylesheetname.xsl"/> <ObSchema name="XML_schema_name.xsd"/> </ObProgram> <ObProgram name="and_so_on"> ... </ObProgram> ... </ObApplication> </ObProgramRegistry>
Each of these elements serves a particular purpose.
For example, the following element identifies the file as a registration file:
<ObProgramRegistry>
while the following element identifies the application to which this registration file applies:
<ObApplication name="the_application_name">
For example:
<ObApplication name="groupservcenter">
The program name identifies the program, or function, within the application, to which the stylesheet, buttons and schema apply:
<ObProgram name="a_program_name">
For example:
<ObProgram name="commonNavBar">
The stylesheet name identifies the base stylesheet that is associated with the program specified by ObProgram.
<ObStyleSheet name="stylesheetname.xsl"/>
For example:
<ObStyleSheet name="gsc_front.xsl"/>
The following element identifies the XML schema file that is associated with the program specified by ObProgram:
<ObSchema name="XML_schema_name.xsd"/>
For example:
<ObSchema name="gsc_front.xsd"/>
Note: There is only one ObStyleSheet element and only one ObSchema element for each ObProgram element. |
The following element identifies an ObButton element that is associated with the program specified by ObProgram. There may be anywhere from zero to many ObButton elements for each ObProgram element:
<ObButton name="a_button_name"/>
For example, in the program name for save, the first button is:
<ObButton name="groupSubscribe"/>
An ObButton is an Oracle Access Manager-specific construct that packages a graphic, mouseover text, and link as a unit to be built into the page.
You cannot change the content of the named button package that is provided in the Output XML. You can, however, remove the entry for the button from the registration file, in which case it does not appear in the finished page. And you can control where and whether the button is displayed using the XSL stylesheet.
Caution: Oracle recommends that only experienced developers consider editing the registration file. Use extreme care if you decide to edit a registration file. |
Following is an excerpt from the User Manager registration file in Identity_install_dir
\identity\oblix\apps\userservcenter\bin\userservcenterreg.xml
with information for the view program highlighted in bold.
Note: The XML schema file name that applies to the OutPutXML data for the view program is usc_profile.xsd and the stylesheet file to be used isusc_profile.xsl . In fact, the usc_profile.xsl stylesheet is used by several functions. For details about this stylesheet, "XSL Stylesheet Content". |
<?xml version="1.0"?> <ObProgramRegistry> <ObApplication name="userservcenter"> <ObProgram name="front"> <ObStyleSheet name="usc_profile.xsl" /> <ObSchema name="usc_front.xsd" /> </ObProgram> <ObProgram name="commonNavbar"> <ObStyleSheet name="usc_profile.xsl" /> <ObSchema name="usc_front.xsd" /> </ObProgram> ... <ObProgram name="deactivateUserArchive"> <ObStyleSheetname= "Deactuser_purgearchiveconfirm.xsl"/> <ObButton name="wfArchivePurgeBack"/> <ObSchema name="usc_deactivateUserPurge.xsd"/> </ObProgram> <ObProgram name="view"> <ObStyleSheet name="usc_profile.xsl"/> <ObButton name="initiateDeactivateUser"/> <ObButton name="userreactivate"/> <ObButton name="userModify"/> <ObSchema name="usc_profile.xsd"/> </ObProgram> <ObProgram name="modify"> <ObStyleSheet name="usc_profile.xsl"/> <ObButton name="userSaveChange"/> <ObButton name="userCancelChange"/> <ObSchema name="usc_profile.xsd"/> </ObProgram> ... </ObApplication> </ObProgramRegistry>
Because the JavaScripts are supplied by WebPass in direct response to requests from the browser, they are located in directories associated with WebPass, rather than with the Identity Server. For example:
WebPass_install_dir\identity\oblix\lang\shared
For more information, see "Directory Structure".
HTML created by PresentationXML has embedded within it references to JavaScript files and functions within the files. A few of these files are associated with specific applications, but most of them are provided under WebPass.
A list of some of the most important of these files, and functions available within them, is provided at "JavaScript Library".
The manner in which Oracle Access Manager presents information, its style, is a direct result of the appearance of the graphical images used and the way in which they are combined on the page. Stylesheets control the way in which the images are combined. The images themselves can be changed, or different image names can be used in the stylesheets.
Note that for particularly complex stylesheets, the transformation engine can run out of stack space. If you run into this issue, you can modify the value of the StringStack parameter in the globalparams.xml file. See "Oracle Access Manager Parameter Files" for details.
Messages in stylesheets depend upon a language. With multiple-language capability, messages have been brought out of the stylesheets and defined separately as variables in msgctlg.xsl (and msgctlg.js for JavaScript files). For details about message catalogs, See"Changing Message Catalogs and MouseOver Text".
In addition, each stylesheet has a corresponding language-specific thin wrapper in:
Identity_install_dir\identity\oblix\lang\langTag\style0
Each wrapper in \style0
includes the main language-neutral stylesheet stored in \shared
:
Identity_install_dir\identity\oblix\lang\shared
The purpose of this new thin wrapper is to segregate the main functionality of the stylesheet template, which is language independent, from language-specific messages in the stylesheets.
Example: basic.xsl wrapper stylesheet
For example a typical wrapper stylesheet, basic.xsl, is located in \style0 and may be in your custom style directory:
Identity_install_dir
\identity\oblix\lang\en-us\style0\basic.xs
Identity_install_dir
\identity\oblix\lang\en-us\
Custom
\basic.xsl
The following example shows basic.xsl content:
<?xml version="1.0" ?> - <!-- Copyright (c) 1996-2005, Oracle Inc. All Rights Reserved. --> - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/"> <xsl:include href="./style.xsl" /> <xsl:include href="../msgctlg.xsl" /> <xsl:include href="../../shared/basic.xsl" /> </xsl:stylesheet>
The basic.xsl wrapper stylesheet includes a pointer to:
msgctlg.xsl, one directory up from your custom directory (in identity\oblix\lang\en-us)
style.xsl file in your custom directory
Due to the change in location of all image files, a new gifPathName variable is defined in style.xsl. For more information, see "Images".
basic.xsl in identity\oblix\lang\shared.
See also "XSL Stylesheet Content".
XSL stylesheets follow a standard developed by the World Wide Web Consortium. See "XSL Validation" for information on the standard, and an introduction to XSL syntax.
As discussed earlier, PresentationXML uses the name of the current program as an index to its registration file, to get the name of an associated XSL stylesheet. For example, if the User Manager application is running the view program, then it locates and uses the usc_profile.xsl file as its stylesheet.
The following is partial content of the User Manager usc_profile.xsl stylesheet file. The information is shown in a compressed format in which each occurrence of <xsl:template represents many lines of XSL which for the sake of clarity are not shown here:
<?xml version="1.0" ?> <!-- Copyright ... --> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/"> <xsl:include href=./basic.xsl" /> <xsl:include href=./selectorinfo.xsl" /> <xsl:include href=./usc_searchform.xsl" /> <xsl:include href=./usc_navbar.xsl" /> <xsl:template match="/"> ... <xsl:template match="oblix:ObProfile"> ... <xsl:template match="oblix:ObProfile/Oblix/ObForm"> ... <xsl:template match="/oblix:Oblix/oblix:WfActorComment"> <xsl:template match="oblix:WfActorComment/oblix:ObForm"> <xsl:template match="oblix:ObHeaderPanel">... <xsl:template match="oblix:ObPanel">... <xsl:template match="oblix:ObAttribute"> ... <xsl:template name ="horizontalButton"> ... </xsl:stylesheet>
The lines beginning with xsl:template match are the top level of a great many lines of XSL instructions, called a template, which tell the XSL Transformer how to build the output page.
For example, the line:
<xsl:template match="oblix:ObProfile">
in effect tells the transformer to look for an occurrence of the oblix:ObProfile element in the OutPutXML and, if it finds it, to begin to apply the instructions following this line in the stylesheet.
In the case of this example stylesheet, building of the HTML begins with the line <xsl:template match="/">. Within that template, the Navigation Bar and the Search Form are built. The remaining templates go on to build the Profile information, including the Header Panel (the one including the user photo) and each of the other panels.
The lines beginning with xsl:include, shown in bold, indicate other XSL files which are to be added in-line to generate the complete XSL stylesheet. These included files can contain references to other included files, and so on. Certain base stylesheet files are used in common by almost all of the applications.
Base stylesheets include:
basic.xsl: Contains templates to define attributes and status and control display information. Contains references to the font.xsl and title.xsl files.
searchform.xsl: Contains templates to create the Searchform line.
navbar.xsl: Contains templates to create the Navigation Bar.
font.xsl: Contains templates to define HTML size, fonts and colors for recurring text such as page headings.
title.xsl: Contains the default titles for the HTML pages.
Each base stylesheet includes other nested stylesheets, and so on. For easy reference, tables giving the names of the most commonly used stylesheets, the names of the templates contained within them, and a brief description of what each template does, are provided in "Stylesheets".
HTML created by PresentationXML has embedded within it references to images. The Oracle Access Manager supplies its own set of GIF images and supports any type of image that can be read by a browser. Because the images are supplied by WebPass in direct response to requests from the browser, they are located in directories associated with Webpass, as described in "Directory Structure".
See also: See "Image Library" for the naming convention for these files.For details about incorporating custom images or styles after upgrading, see the Oracle Access Manager Upgrade Guide. |
gifPathName and jsPathName Variables
Due to the change in location of all image files, a new gifPathName variable is defined in style.xsl. In addition to style.xsl, the following file also includes the gifPathName variable to mention the path for image locations:
install_dir\oblix\lang\langTag\msgctlg.js
For more information about msgctlg files, see "Modifying Catalog Files".
Note: Stylesheets refer to the gifPathName variable to locate the image directory. JavaScript files refer to the jsPathName variable. |
A language independent stylesheet picks up the images from the modified image path mentioned by the gifPathName variable, which is important for two reasons:
It prevents hard-coding of URLs in the stylesheets and makes it easier to reuse the same stylesheet across styles.When customizing stylesheets, you should use this global variable whenever constructing a URL path to a GIF.
It incorporates the current language and current style tag and generates the correct path.
Example: style.xsl with variables highlighted
The style.xsl wrapper resides in \style0 and can reside in your custom directory:
Identity_install_dir
\identity\oblix\lang\en-us\style0\style.xs
l
Identity_install_dir
\identity\oblix\lang\en-us\
Custom
\style.xsl
A sample style.xsl is as follows.
<?xml version="1.0" encoding="ISO-8859-1"?> - <!-- Copyright (c) 1996-2005, Oracle All Rights Reserved. --> - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/"> <xsl:variable name="styleName">style0/</xsl:variable> <xsl:variable name="localeName">en-us</xsl:variable> - <xsl:variable name="gifPathName"> ../../../lang/ <xsl:value-of select="$localeName" /> / <xsl:value-of select="$styleName" /> </xsl:variable> <xsl:variable name="jsPathName">../../../lang/shared</xsl:variable> - <xsl:variable name="cssPathName"> ../../../lang/ <xsl:value-of select="$localeName" /> / <xsl:value-of select="$styleName" /> /coreid.css </xsl:variable> <xsl:variable name="pageLayoutDir">LTR</xsl:variable> </xsl:stylesheet>
This section treats several of the components described earlier as parts of a library of information used to implement PresentationXML as if it were a programming language. It provides more detail and pinpoints the location of the files in directories.
The Identity System can be installed starting at the root directory or in a specified subdirectory. For example:
Default on Windows: C:\Program Files\COREid\identity
Default on Unix: /opt/coreid/identity
In this manual: Identity_
install_dir
\identity
Prior to version 6.5, the PresentationXML library was provided under two directories and distributed depending upon how the files were likely to be used.
Version 6.5 and later versions include Language Packs that enable you to display static information to users in their native language. English is the default language for which no Language Pack is required. All Oracle Access Manager installations include a directory named with the en-us language tag (langTag).
When you install additional Language Packs you will see other langTag directories. For example, a French Language Pack results in a directory named fr-fr. For details about installing Language Packs, see theOracle Access Manager Installation Guide.
For version 6.5 and later, the default directory structure for PresentationXML Libraries is summarized as follows:
Identity_install_dir\identity\oblix\apps\AppName\bin Identity_install_dir\identity\oblix\apps\AppName\bin Identity_install_dir\identity\oblix\lang\langTag Identity_install_dir\identity\oblix\lang\langTag\style0 Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\langTag WebPass_install_dir\identity\oblix\lang\langTag\style0 WebPass_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\WebServices\XMLSchema
Figure 2-4 and Figure 2-5 show a default Identity Server Directory structure. Notice that the \en-us directory and the \shared directory reside at the same level in the \lang directory. Also notice that the Identity System application-specific directories reside under \apps (userservcenter, objservcenter, groupservcenter).
The contents of default Identity System and WebPass directories are introduced here.
The contents of the default directories are outlined in Table 2-3. See the full list of applications, in the AppName column.
Table 2-3 Default PresentationXML Libraries
Default Identity System Directories | Contents |
---|---|
Where AppName can be common, groupservcenter, objservcenter, userservcenter, and so on. |
Registration and parameter files specific to the application. Note: Dynamically-loadable code for applications is included in Identity Server executables. |
Where langTag represents an installed language, such as en-us (English) or fr-fr (French). |
Message files for various applications. |
|
|
|
XSL stylesheet templates for various applications |
The contents of the default WebPass directories identified earlier is outlined in Table 2-4.
Table 2-4 Default WebPass PresentationXML Libraries
Default WebPass Directories | Contents |
---|---|
|
Contains message files for various applications. |
|
|
|
|
|
Contains XML schema files for specific applications. |
The differences between content of the Identity Server and WebPass PresentationXML directories are outlined in "Differences Between Identity Server and WebPass Directory Content".
Differences Between Identity Server and WebPass Directory Content
Summary of differences as follows:
The XMLschema directory has no effect on PresentationXML operation and exists only on WebPass.
JavaScripts and image files are always provided by WebPass Due to the change in location of all image files, a new gifPathName variable is defined in \identity\oblix\lang\langTag\style0\styles.xsl. A language independent stylesheet picks up images from the modified image path mentioned by the variable. Wrapper stylesheets include the styles.xsl stylesheet file. styles.xsl also contains the path for JavaScripts.
Parameter, message, and registration files are used only by Identity applications, as part of the process that generates the OutPutXML.
Stylesheets are available under both Identity Server and WebPass because they can be used in either:
Server-side processing (the Identity Server builds the completed XSL stylesheet).
Client-side processing (WebPass assists the client browser to build the final stylesheet by sending it pieces of other stylesheets to be included in-line).
For example:
Before v6.5: Identity_install_dir
\identity\oblix\apps\
AppName
Before v6.5: WebPass_install_dir
\identity\oblix\apps\
AppName
where AppName represents Group Manager (groupservcenter), Org. Manager (objservcenter), User Manager (userservcenter), and the like.
The AppName directory included include three significant subdirectories:
Before v6.5: AppName
\bin
Before v6.5: AppName
\ui
Before v6.5: AppName
\xmlschema
Note: Oracle Access Manager includes Language Packs that allow you to display static information to users in their native language. English is the default language for which no Language Pack is required. As a result, the directory structure and location of specific files has changed. |
Following discussions provide more information on the content of the directories identified in the previous paragraphs.
Identity_install_dir\identity\oblix\apps\AppName\bin
The AppName
directory refers to specific applications, including:
common
groupservcenter
objservcenter
userservcenter
and others
Each AppName
\bin
directory contains a registration file, as discussed in "Registration Files". In addition, each AppName
\bin
directory contains a small number of XML files that contain parameters for the specific application. All application-specific subdirectories include the same types of information. Although, the userservcenter\bin directory also includes several certificate files.
For example, in groupservcenter\bin, you will find the following files:
groupservcenterreg.xml: The registration file for the Group Manager application.
groupservcenterparams.xml: This file, and other files ending in params.xml, contain parameters that are used to guide execution of the application:
gsc_wf_params.xml: Create workflow, remove workflow, change attribute workflow parameters. The following files duplicate this information and are needed for special handling required for the IBM SecureWay directory server:
gsc_wf_params-base.xml gsc_wf_params-sw.xml
gsc_wfqs_params.xml: Create group basic template parameters.
gscaclparams.xml: Example that shows a set of parameters and their value ranges for simple access control. Sample data is included that is not meant to be used in any deployment.
See also: See "Oracle Access Manager Parameter Files" for a list of all parameter files whose content is designed to be changed by the user. |
Note: Do not change the content of any of these files unless the named file is listed in "Oracle Access Manager Parameter Files", the parameter is described there, and the description does not forbid you to change the parameter. |
Note: AppName .dll files, available before version 6.5, contained logic that the Identity Server executed for each application. Application module logic and libraries are now compiled in the Identity Server executable. |
Identity_install_dir\identity\oblix\lang\langTag
To support multiple languages, Oracle Access Manager provides a specific named directory for each installed language. For example, \lang\en-us contains English language files; \lang\fr-fr contains French language files, and so on. Both the default style directory and any custom style directories you create are stored within each installed language directory.
Identity_install_dir\identity\oblix\lang\en-us\NewStyle Identity_install_dir\identity\oblix\lang\en-us\style0 Identity_install_dir\identity\oblix\lang\fr-fr\NewStyle Identity_install_dir\identity\oblix\lang\fr-fr\style0
Each langTag directory also contains message files for various applications in a specific language, such as English. A \help directory is also stored here.
You may customize messages in each langTag directory by editing specific msg.xml files.
Identity_install_dir\identity\oblix\lang\langTag\style0
The \style0 directory within each langTag directory provides default wrapper stylesheets that are specific to each application. For example:
gsc_ is the prefix for Group Manager wrapper stylesheets.
osc_ is the prefix for Org Manager wrapper stylesheets.
usc_ is the prefix for User Manager wrapper stylesheets.
wf_ is the prefix for workflow wrapper stylesheets.
There are others.
Each default wrapper stylesheet points to default global stylesheets in the \shared directory. In addition, several common image (GIF) files are stored here. When you add a style using the Configure Styles function in the Identity System Console, and copy from the Classic Style, the contents of \style0 are duplicated in your custom directory.
When customizing a style, you may overwrite a default wrapper stylesheet in your custom directory with a copy of the \shared stylesheet that you intend to customize. No wrapper stylesheet in your custom directory should inherit from (or reference) a default global stylesheet in the \shared folder.
The giflist.xml file included in previous versions is not available.
Note: Oracle recommends that you retain the files in \style0 as they are in case you need to revert to the default style. See "Customizing Oracle Access Manager" for more information. |
Identity_install_dir\identity\oblix\lang\shared
The \shared directory contains default global stylesheets that apply to various applications in all languages.
You may edit stylesheets in \shared to institute a global change for all languages. However default stylesheets in \shared, and in \style0, will be updated periodically by Oracle. A customized stylesheet in \shared or \style0 may be overwritten during product patches or upgrades. Other stylesheets may depend on the updates making it risky to overwrite an updated default stylesheet with the back up copy of a customized style. A better practice is to copy a default stylesheet from \shared into your custom directory, then customize the copy.
Note: Oracle recommends that you retain the files in \shared as they are in case you need to revert to the default style. |
WebPass_install_dir\identity\oblix\lang\langTag
This directory contains message catalog files for various applications but is not an exact duplicate of the langTag directory on the Identity side:
Copies of several message files
Additional message files, such as webpassmsg.xml and others
HTML files such as ldap_personoc.html
This directory also includes a help directory, and a docs directory for Web server related files. Again, you may edit message files here and propagate changes to other WebPass hosts.
WebPass_install_dir\identity\oblix\lang\langTag\style0
Contains copies of default XSL wrapper stylesheets for various applications from Identity_install_dir
\identity\oblix\lang\
langTag
\style0.
Also included are the image files used when presenting the page, which are always provided by WebPass as direct responses to browser requests.
Note: Oracle Access Manager relies on the images provided in this directory. Oracle recommends that you do not alter default images. |
After you add a style to Oracle Access Manager and customize stylesheets, you will create the same style-related directory structure on the WebPass. You must copy all images you intend to use into your custom directory structure on WebPass. Even if you have made no changes to images you must still:
Copy Images From: WebPass_install_dir
\identity\lang\en-us\style0
Copy Images To: WebPass_install_dir\identity\lang\en-us\
CustomStyle
As with other default style files, images may be updated by Oracle periodically.
WebPass_install_dir\identity\oblix\lang\shared
This directory contains default global files that WebPass uses in response to requests:
JavaScripts used by WebPass
Copies of XSL stylesheets in Identity_install_dir
\identity\oblix\lang\shared
directory for use with client-side processing.
As with other default style files, these may be updated by Oracle periodically. Oracle recommends that you do not alter default files.You may copy and customize JavaScripts using the same methodology as if modifying a stylesheet on the Identity Server side.
WebPass_install_dir\identity\oblix\WebServices\XMLSchema
This directory contains the XML schemas, as xsd files, that define elements specific to various applications. For example
gsc_... identifies Group Manager files.
osc_... identifies Org Manager files.
usc_... identifies User Manager files.
workflow... identifies Workflow files.
The XMLSchema has no affect on PresentationXML and is included only on WebPass.
As with other default style files, these may be updated by Oracle periodically.
The Oracle Access Manager system relies on these files. Oracle recommends that you retain the files in this directory as is.
As discussed in the previous sections, the default XSL stylesheets and wrapper stylesheets for various Identity System applications can be found in the following directories:
Identity_install_dir\identity\oblix\lang\langTag\style0 -- wrapper stylesheets Identity_install_dir\identity\oblix\lang\shared -- stylesheets WebPass_install_dir\identity\oblix\lang\langTag\style0 WebPass_install_dir\identity\oblix\lang\shared
On WebPass, copies are included for client-side processing if that method is used.
The following base stylesheet files provide a foundation for all other stylesheets and contain relative pointers to other stylesheets:
basic.xsl: Provides templates to define attributes and status and control display information, including references to the font.xsl and title.xsl files.
For more information, see "basic.xsl".
font.xsl: Contains templates to define HTML size, fonts and colors for recurring text such as page headings.
For more information, see "font.xsl".
title.xsl: Contains the default titles for the HTML pages.
For more information, see "title.xsl".
navbar.xsl: Provides the template to define the Navigation Bar.
For more information, see "navbar.xsl".
searchform.xsl: Provides templates to create the Searchform line. The following searchform.xsl files appear as well, and all point to searchform.xsl:
gsc_searchform.xsl
osc_searchform.xsl
usc_searchform.xsl
For more information, see "searchform.xsl".
Important: Oracle periodically updates stylesheets and recommends retaining default stylesheets to serve as a predictable stylesheet library. |
The basic.xsl wrapper stylesheet in the \lang\en-us\style0 or your custom directory provides references to style.xsl, msgctlg.xsl, and to the basic.xsl stylesheet located in the \shared subdirectory.
The global, language-neutral basic.xsl file in the following directories includes the variables in Table 2-5 and the templates in Table 2-6:
Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\shared
Table 2-5 Variables Defined in basic.xsl
Name | Description |
---|---|
textSLength |
The default length for a textbox. |
textSMaxLength |
The maximum length for a textbox. |
namePrefix |
Oblix internal, do not change. |
singlequote |
Defines a constant for the single quote character. This is specified as a character that needs to be handled in a special manner and is required for literal strings in JavaScript code enclosed in single quotes. |
charsToEscape |
Used in the |
Table 2-6 identifies actual templates available in basic.xsl.
Table 2-6 basic.xsl Templates
Name | Description |
---|---|
oblix: ObDisplay |
Each display type (for example checkbox, textbox, bitstring, and so on) is nested within the oblix:ObDisplay element. This matching template, sometimes called the Dispatcher, calls the corresponding display type template to properly generate the HTML for that display type. Additional HTML logic is added to properly include the + or - button in modify mode. |
oblix:ObBitString |
Generates the bitstring display type data as HTML text in view mode or as an HTML textbox in modify mode. |
oblix:ObBoolean |
Generates the Boolean display type data as text strings in view mode or radio buttons in modify mode. |
oblix:ObCheckBox |
Generates the checkbox display type data as text strings in view mode or an HTML checkbox in modify mode. |
oblix:ObDate |
In view mode this template generates the date display type as text strings, using a format corresponding to the date type specified (ObMonthDYDate, ObDMYDate, for example). In modify mode this template generates the date display type as an HTML select box (one for year, one for month, and one for day). This template calls the ObDateValue template to generate the actual select boxes. |
oblix:ObDateValue |
In view mode this template generates one entered value of the date display type data as a text string with a format corresponding to the date type specified (for example ObMonthDYDate, ObDMYDate). In modify mode it generates an HTML select box (one for year, one for month, and one for day). |
oblix:ObDn |
In both view and modify mode, generates the dn display type as hyperlink text. The dn value will also be prepended with an image, if one is supplied from the XML. |
oblix:ObEmail |
In view mode generates the email display type as hyperlinked text in the form mailto:<email address>). In modify mode, this is an HTML text box. |
oblix:ObFacsimile TelNum |
In view mode, this template generates the facsimileTelNum display type data as a text string with the fax value first, followed by optional parameters describing whether it is TwoDimensional, FineResolution, b4Length, a3Width, b4Width, uncompressed, and unlimitedLength. In modify mode, the text string is displayed as an HTML textbox and the parameter properties are displayed as checkboxes. |
oblix:ObGeneric Selector |
Generates the generic selector display type data as hyperlinked text in both view and modify mode. If the data is for a user, a user image is prefixed. If the data is for a group, a group image is prefixed. If the data is an object, an object image is prefixed. In addition, the modify mode also generates the selector button. |
oblix:ObGif |
Generates the GIF display type data as an image using the src, width, height, and alt information from the XML, in both view and modify mode. In modify mode, a file upload box is also generated. |
oblix:ObGifUrlText |
A named template that is called by ObGifUrl. Used only in modify mode to generate the gifurl information as a textbox with the specified length and maxlength. |
oblix:ObGifUrl |
In both view and modify mode, generates the gifurl display type data as an image using ObImage's XML attributes obhref (the hyperlink), obalt (the alternate text), obwidth (the width of the image), and obheight (the height of the image). In modify mode, an additional text box is generated by calling the template ObGifUrlText. |
oblix:ObLocationDn |
Generates the location dn display type data as a link by calling the ObLink template. |
oblix:ObMedia |
Generates the media display type data as a hyperlink with an image, if one is supplied or the specified display name, if one is supplied. For modify mode, an additional file browse button is also generated. |
oblix:ObPassword |
In modify mode, generates an HTML password input box with the specified length and max length. If oboldpswd is true, then the old password is also prompted for, using a password input box. (This element is not used in view mode). |
In view mode, generates the postal address display type value as a text string. In modify mode, the values are presented as modifiable data in text boxes. |
|
In modify mode, each value is displayed as modifiable data in a textbox. A querybuilder button is also generated. (This element is not used in view mode). |
|
In view mode, generates the radio display type values as text strings. In modify mode, the values are generated as HTML radio buttons. |
|
oblix:ObSelect |
In view mode, generates the select display type values as text strings. In modify mode, the values are generated as HTML select boxes. |
Generates the SMIMECertficate display type as text strings. |
|
In view mode generates the textM display type value as a text string. In modify mode the values are generated as HTML multi-line text boxes with the specified columns and rows. |
|
In view mode, generates the textS display type value as a text string. In modify mode, the values are generated as HTML single-line text boxes with a specified maxlength and length. |
|
In view mode, generates the numeric string display type value as a text string. In modify mode, the value is generated in a text box with the specified maxlength and length, along with a JavaScript validation to ensure that the text field only accepts numeric values. |
|
Generates the PC Data text in the Oblix:ObValue element. |
|
Generates an HTML applet. Information includes name, codebase, code, width, height, align, target, and archive. If the applet requires input parameters, they are specified in the oblix:ObParam element. |
|
Calls the oblix:ObScript template for each ObScript element within the ObScripts element. |
|
Generates the script tag to allow the JavaScript specified in the Oblix:ObScript element to be referenced within the HTML. |
|
Generates a button, either a hyperlink text or image, using the information provided in the XML. Information includes the href, mouse over, and optional image. If an image is not specified the anchor text is displayed. |
|
Generates the HTML input tag using the specified information in the XML element. |
|
In view mode generates a hyperlink with the specified href and mouse over values, along with either an image or a text string. In modify mode a text box is generated. |
|
Generates an image using the specified obwidth, obheight, obalt, and href values. |
|
A called template that generates the proper HTML tag to enable the "request a ticket to remove an attribute" functionality. |
|
A called template that generates the proper HTML tag to enable the "request a ticket to modify an attribute" functionality. |
|
A called template that generates the date choices for modify mode. |
|
A called template that generates the month select box in modify mode. |
|
A called template that generates the day select box in modify mode. |
|
A called template that generates the year select box (by default, 1993 - 2012) in modify mode. |
|
A called template that generates the hour select box (00 - 23) in modify mode. |
|
A called template that generates the hour select box (00 - 12) in modify mode. |
|
A called template that generates the minute or the hour select box (00 - 59) in modify mode. |
|
A called template that generates hidden HTML input tags, intended for internal purposes. This is called by the Oblix:ObDisplay template. |
|
A called template that generates the proper HTML tag to enable the "add more values" functionality (The + button). |
|
A called template that generates the proper HTML tag to enable the "remove a value" functionality (The - button). |
|
A called template that adds the onX event which can be any of: onChange, onClick, onDblClick, onDragStart, onFilterChange, onHelp, onKeyDown, onKeyPress, onMouseDown, onMouseMove, onMouseOut, onMouseOver, onMouseUp, onSelectStart, or disabled. |
|
Generates the error message. |
|
Generates the specified text message. |
|
A called template that generates hidden HTML input tags, intended for internal purposes. |
|
A called template that generates values in a table format. |
|
A called template that generates link values in a table format. |
|
A called template that generates each link values as a checkbox in a table format. |
|
A called template that converts the input parameter from x to Obx, changing hyphens to underscores. |
|
A called template that adds line breaks to a string, in the places where the string contains 
 |
|
A called template that escapes characters in preparation for calling a JavaScript. |
|
A called template that generates an error display if the Java Runtime Environment 1.3 or higher is needed but not available. |
This stylesheet contains templates to define HTML size, fonts and colors for recurring text such as page headings. The font.xsl file in the following directories includes the variables in Table 2-7 and templates in Table 2-8.
Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\shared
Table 2-7 Variables Defined in font.xsl
Name | Description |
---|---|
Defines the size of the heading for the page. |
|
Defines the color of the heading for the page. |
|
Defines the font of the heading for the page. |
|
Defines the size of the subheading for the page. |
|
Defines the color of the subheading for the page. |
|
Defines the font of the subheading for the page. |
|
Defines the size of the content title (for example the attribute display name in a profile page). |
|
Defines the color of the content title. |
|
Defines the font of the content title. |
|
Defines the size of the content text (for example the attribute value in a profile page). |
|
Defines the color of the content text. |
|
Defines the font to be used for the content text. |
|
Defines the size of the warning message. |
|
Defines the color of the warning message. |
|
Defines the font to be used for the warning message. |
|
Defines the size of the anchor text to be used with login.xsl and logout.xsl. |
|
Defines the color of the anchor text for login.xsl and logout.xsl. |
|
Defines the font of the anchor text for login.xsl and logout.xsl. |
Table 2-8 identifies the templates in font.xsl.
Table 2-8 Templates Defined in font.xsl
Name | Description |
---|---|
A called template that is used to set the proper color, size, and font for the page header. (for example the word Profile, which is the title of a profile page). |
|
A called template that is used to set the proper color, size, and font for the sub heading. (for example the Panel name in a profile page). |
|
A called template that is used to set the proper color, size, and font for the content title. (for example the attribute display name in a profile page). |
|
A called template that is used to set the proper color, size, and font for the content text. (for example the attribute value in a profile page). |
|
A called template that is used to set the proper color, size, and font for the page warning. |
|
A called template that is used to set the proper color, size, and font for the anchor text created by login.xsl and logout.xsl. |
This stylesheet the default titles for the HTML pages. The title.xsl file in the following directories include the variables in Table 2-9. There are no templates in title.xsl.
Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\shared
Table 2-9 Variables Defined in title.xsl
Name | Description |
---|---|
HTML title for all Publisher pages. |
|
HTML title for all User Manager pages. |
|
HTML title for all Group Manager pages. |
|
HTML title for all Organization Manager pages. |
|
HTML title for all Query Builder pages. |
|
HTML title for all Selector pages. |
|
HTML title for all Lost Password Management pages. |
|
HTML title for all common pages shared across all applications. |
|
For internal use only; used to determine the context of the current page. |
|
Internal use only; used to determine the context of the current page. |
|
Internal use only; used to determine the context of the current page. |
|
Internal use only; used to determine the context of the current page. |
In the \shared subdirectory, navbar.xsl provides the template to define the Navigation Bar. The following files in the \shared subdirectory also point to navbar.xsl: gsc_navbar.xsl, osc_navbarm.xsl, usc_navbar.xsl.
The navbar.xsl file in the following directories include the templates in Table 2-10. There are no variables in navbar.xsl.
Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\shared
Table 2-10 Templates Defined in Navbar.xsl
Name | Description |
---|---|
oblix:ObNavbar |
Generates the Navigation Bar (Navbar) that appears at the top of every Identity System page. The navbar is made up of several significant parts: Logged in user identification, a list of selectable applications (User Manager, Organization Manager, and so on), Help/About/Logout buttons, application functionality (for example My Identity, Reports, and so on), and Tabs (if there are multiple tabs). |
oblix:ObApps |
Generates the list of selectable applications. |
localButton |
A called template that generates a button by filling in the HTML information about the href, mouseover, mouseout, and image or anchor text. |
oblix:ObApplication/ oblix:ObTabs/oblix:ObButtons |
Generates the buttons used for selecting different tabs. |
oblix:ObApplication/ oblix:ObFunctions/oblix:ObButton |
Generates the buttons used for selecting the different functionalities within the application (for example My Identity). |
oblix:ObApplication/ oblix:ObTitle/oblix:ObButton |
For internal use only, used to set the current context. |
This template was previously distributed but now templates to create the Searchform line are located in searchform.xsl. The following searchform.xsl files appear as well, and all point to searchform.xsl:
gsc_searchform.xsl osc_searchform.xsl usc_searchform.xsl
The searchform.xsl file in the following directories include the templates in Table 2-11. There are no variables in searchform.xsl.
Identity_install_dir\identity\oblix\lang\shared WebPass_install_dir\identity\oblix\lang\shared
Table 2-11 Templates Defined in searchform.xsl
Name | Description |
---|---|
oblix:ObSearchForm |
Generates the Searchform, which is located directly beneath the Navigation Bar on most pages. The Searchform may contain many SearchRows. |
oblix:ObSearchForm/ oblix:ObSearchRow |
Generates one row of the search functionality. A row consists of 2 select boxes and one text box, usually one for each search request, such as a search for "full name" "that contains" "John". |
oblix:ObSearchForm/ oblix:ObAdvanced Search |
Generates the search more, search less, and search all buttons if the advanced search capability is enabled. |
As mentioned earlier, the OutPutXML information generated by each program within each Identity System application is hard-coded and is not directly changeable by users. The content of the OutPutXML is not controlled by the content of the XML schema file. The file is provided only as a developer's aid, to help you design XSL stylesheets to work with the OutPutXML. Oracle recommends that you not change any of the XML schema files.
The following is presented for information only. The XMLSchema directory in WebPass_install_dir
\identity\oblix\WebServices
contains several schema files specific to each application. For example:
gsc_administrationMain.xsd ... osc_administrationMain.xsd ... usc_administrationMain.xsd ... and others ...
If you look at these files, you will see that some contain element definitions that exist only within that file, and many contain references to other schema files.
If you trace nested references deeply enough, you will come to the following six files, which are provided under the XMLSchema directory for the common application:
navbar.xsd: Defines the content for the Navigation Bar, the top two lines of each page, including the application name, help and logout buttons, and the various tabs to select other modules within the application.
searchform.xsd: Defines the SearchForm line, the line available on some pages, that starts with the graphic labeled search. It may include additional lines for more complex search combinations.
component_panel.xsd: Defines the content for profiles, the sets of descriptive information for users, groups or organizations.
component_basic.xsd: Defines many of the lowest level elements, and includes displaytype.xsd and error.xsd.
displaytype.xsd: Defines formatting for each of the Oracle Access Manager display types.
error.xsd: Defines the ObError element.
The rest of this section describes the elements that are defined within each of these files.
Note: It is strongly recommended that you leave the content of these files untouched, to serve as a predictable template library. |
The displaytype.xsd file in WebPass_install_dir
\identity\oblix\WebServices\XMLSchema
contains the elements described in Table 2-12. All elements in this file are in the Oblix namespace.
Table 2-12 displaytype.xsd Schemas
Name | Description |
---|---|
ObDisplay |
An element that contains information about a value (or set of values) being generated. This element usually maps to one of the display types such as email or date. This element may contain two children: the element ObDisplayProperties, which is optional, and a required element whose name maps to the display type (for example, ObCheckBox or ObDate). This element contains the following required attributes: obname: The name, usually the attribute name, for the value being generated. obdisplayName: The display name/user friendly name/printed name. obdisplayType: The display type for this value. obsemanticType: The semantic type for this value). obmode: One of the list: view, modify, or plain. obshowLabel: True or false, indicating whether to show the display name when outputting this value. obrequired: True or false, indicating whether this is a required value, meaning there must be at least one value entered by the user in modify mode). obcardinality: SingleValued or multiValued, indicating whether this is a single-valued or multi-valued attribute. obcanRequest: True or false, indicating whether the user can change this value in modify mode. |
ObDisplay Properties |
Contains zero or more ObDisplayProperty elements. |
ObDisplayProperty |
Contains the necessary display property for an onX event, which can be onChange, onClick, onDblClick, onDragStart, onFilterChange, onHelp, onKeyDown, onKeyPress, onMouseDown, onMouseMove, onMouseOut, onMouseOver, onMouseUp, onSelectStart, or disabled. The XML attribute obname contains the onX event name and the XML attribute obvalue contains the value for the onX event. |
ObBitString |
Describes the BitString display type. Contains zero or more ObValue elements, each corresponding to a value. In addition, there are two optional XML attributes: oblength, for the length of the textbox and obmaxLength for the maximum length of the textbox. |
ObBoolean |
Describes the Boolean display type. Contains a required XML attribute obvalue which contains the value true or false. |
ObButton |
Describes a button. A button contains six optional XML attributes: obaction: The action. obmouseover: The mouse over message. obhref: The href. obimageUrl: The location of the image for the button. obanchorText: The alternate text if there is no image. target: Provided for future use and currently not used. |
ObCheckBox |
Describes the checkbox display type. Contains zero or more ObChoice elements. |
ObChoice |
Describes a choice. Usually nested within a display type that permits a choice, such as ObCheckBox. Contains an optional XML attribute obselected. Possible values for obselected are true or false. The default value when this attribute is not specified is false. If a value is selected, it means that the value is one that has been chosen by the user. If a value is not selected, that means it is a possible choice but not one actually chosen by the user. In addition the ObChoice element contains a required XML attribute obdisplayName corresponding to the display name (the user friendly name) for this choice. |
ObDate |
Describes the date display type. Contains zero or more ObDateValue elements. In addition, it contains the following optional attributes: obseparator, the string separating the parts of the date. If this is not specified, the default value is /. obformat: The format in which the date is to be presented. If not specified, the default value is USStandard. Possible values include USStandardFull, EUSStandard, EUSStandardFull, and USStandard. obdateType: The manner in which the date is carried as data. Possible values include ObIntegerDate, ObMDYDate, ObDMYDate, ObDMonthYDate, ObISO8601Date, and ObUnknownDate). |
ObDateValue |
Describes a date value. Contains the following required XML attributes: obmonth: A text string that represents the month. obday: A text string that represents the day. obyear: A text string that represents the year. In addition an optional XML attribute obbadDate describes whether the given date is malformed. The default value for the obbadDate attribute is false meaning the date is not malformed. Possible values are true and false. |
ObDn |
Describes the dn display type. Contains zero or more obLink elements. |
ObEmail |
Describes the email display type. Contains zero or more ObValue elements. In addition, the ObEmail element may contain two optional XML attributes: oblength: The actual length of the textbox. obmaxLength: The maximum allowed length of the textbox. |
ObFacsimileTelNum |
Describes the facsimile telephone number display type. Contains zero or more ObValue elements and zero or more ObFaxParam elements. |
ObFaxParam |
Contains an XML attribute obdisplayName. |
ObForm |
Contains information for generating a form. Contains zero or more ObInput elements. In addition, it contains: obname: The required XML attribute providing the name of the form. obaction: An optional XML attribute providing the action to take when the form is submitted. obenctype: An optional XML attribute providing the encryption type for the form. obmethod: An optional XML attribute specifying the method, either post or get, for this form. The default method is post. |
ObGenericSelector |
Describes the generic selector display type. Contains zero or more ObLink elements and at most one optional ObButton element. |
ObGif |
Describes the GIF display type. Contains zero or more ObImage elements. |
ObGifUrl |
Describes the gifurl display type. Contains zero or more ObImage elements. In addition it contains two optional XML attributes: oblength: The length of the textbox obmaxLength: The maximum length of the textbox. |
ObLocationDn |
Describes the location dn display type. Contains zero or more ObLink elements. |
ObMedia |
Describes the media display type. Contains zero or more ObLink elements. |
ObMime |
Describes the mime display type. Contains a required XML attribute obtype, and an optional XML attribute obfileExt (used to define file extensions). |
ObPassword |
Contains zero or more ObValue elements. Additionally, it may contain three optional XML attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox. oboldpsw: Which indicates whether to display information about the old password. Possible values for the oboldpsw attribute are true and false. |
ObPostalAddress |
Contains zero or more ObPostalValue elements. Contains two optional XML attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox. |
ObPostalSubString |
PC Data containing the postal sub string. |
ObPostalValue |
Contains zero or more ObPostalSubString elements. |
ObSelect |
Describes the select display type. Contains zero or more ObChoice elements. In addition, it contains two optional XML attributes: obmultiple: True or false; the default value is false. obsize: The size of the select box. |
ObTextM |
Describes the textM display type. Contains zero or more ObValue elements. In addition, it may contain three optional attributes: obrows: The number of rows for the multi-line textbox. obwrap: Indicates whether the text should wrap, and takes the values true and false. obcols: The number of columns for the multi-line textbox). |
ObTextMessage |
PC Data describing a text message. Usage for this element is context dependent. One frequent use is to output an error message. |
ObTextS |
Describes the textS display type. Contains zero or more ObValue elements and zero or more ObTextMessage elements. In addition, it may contain two optional attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox. |
ObQueryBuilder |
Describes the query builder display type. Contains zero or more ObValue elements and an optional ObButton element. In addition, it may contain two optional attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox. |
ObRadio |
Describes the radio display type. Contains zero or more ObChoice elements. |
ObSMIMECertificate |
Contains zero or more ObSMIMEValue elements. In addition, it contains three optional ObButton elements. |
ObSMIMEValue |
Contains zero or more ObNameValuePair elements and two optional ObButton elements. |
ObNameValuePair |
Contains two required XML attributes: obcertinfo: Which has three possible values: issuer, validfrom, and validto. obcertvalue: Which is the value that is described by this ObNameValuePair. |
ObScript |
Contains information for including a script. The name of the script is described by the required XML attribute obname. |
ObScripts |
Contains one or more ObScript elements. |
ObValue |
PC Data containing a value. |
ObImage |
Contains one required XML attribute: obhref: The href Also contains three optional XML attributes: obalt: The alt text. obwidth: The width of the image. obheight: The height of the image. |
ObInput |
Contains the information required to generate an HTML input tag. Contains up to three XML attributes: obtype: The type of input (required). obname: The name of the input (required). obvalue: The value of the input (optional). |
ObLink |
Contains zero or more ObImage elements and zero or more ObMime elements. In addition, it contains up to three XML attributes: obhref: The href (required). obmouseOver: The mouse over message for the link (optional). obdisplayName: The display name for the hyperlink (optional). |
ObNumericStr |
Contains zero or more ObValue elements. In addition, it may contain two optional XML attributes: oblength: The length of the textbox. obmaxLength: The maximum length of the textbox. |
ObApplet |
Contains information describing an applet. Contains zero or more ObParam elements, each describing a parameter for the applet. In addition, it contains the one optional XML attribute obarchive and the required XML attributes obname, obtarget, obcodeBase, obcode, obwidth, obheight, and obalign, all of which map to information required in the HTML applet tag. |
ObParam |
Contains the name and value for a parameter, in the form of two required attributes: obname and obvalue. |
The component_basic.xsd file in WebPass_install_dir
\identity\oblix\WebServices\XMLSchema
contains the elements described in Table 2-13. All elements in this file are in the oblix namespace.
Table 2-13 component_basic.xsd Schemas
Name | Description |
---|---|
ObRequestInfo |
Internal use only. |
ObStatus |
Contains the returned status value, either 0 or 1, for the request. |
ObVariableText |
Contains one ObDisplay element. |
ObAttribute |
Contains zero or more ObDisplay elements and an optional ObTextMessage element. In addition, an optional XML attribute obattrName may be used to specify the attribute name. |
The navbar.xsd file in WebPass_install_dir
\identity\oblix\WebServices\XMLSchema
contains the elements described in Table 2-14. All elements in this file are in the oblix namespace.
Table 2-14 navbar.xsd Schemas
Name | Description |
---|---|
ObTabs |
Consists of zero or more buttons used for describing the different tabs configured for the current application. |
ObNavbar |
Describes the navigation bar. It may contain up to 8 optional elements: ObRequestInfo, ObScripts, ObMisc, ObApps, ObForm, ObApplication, ObFunctionsButton, and ObStatus. In addition, a required XML attribute obbgcolor specifies the color of the background for this page. |
ObMisc |
Describes the buttons that will be used for help, about, and logout. |
ObApps |
Contains zero or more ObApplication elements. Each ObApps element describes an application, such as User Manager or Organization Manager. |
ObApplication |
Describes the details of a specific application, usually nested within ObApps. Contains any of the following four elements: ObButtons: Specifies the URL/button information to get to that application. This information is only filled in if the user is not in that application. ObFunctions: Specifies the functions available for this page. ObTabs: Specifies the tabs to be used on this page, if any. ObTitle: Specifies the title image for this application. |
ObFunctions |
Describes the functions available on the current page. Consists of: ObButtons: For example, non-workflow and administrative functionality such as configure proxy, deactivate user or create user. There are zero or more of these. ObWorkflowFunctions: For example, workflow incoming request, workflow outgoing request or workflow ticket search form. ObAdminFunctions: Administrative functions, such as delegated administration or workflow definition. |
ObAdminFunctions |
Describes the administrative functionality such as workflow definition and delegated administration. |
ObWorkflow Functions |
Describe the workflow functionality such as workflow incoming request, workflow outgoing request or workflow ticket search form. |
ObTitle |
Consists of zero or more buttons that describe the image that applies to the current application. |
ObApplicationFunc |
Provides further context defining where the user is in screen navigation. This element is not used unless the user is past first level navigation. An example is the navigation information that will be contained here after the user clicks on "Configuration" |
The searchform.xsd file in WebPass_install_dir\identity\oblix\WebServices\XMLSchema contains the elements described in Table 2-15. All elements in this file are in the oblix namespace.
Table 2-15 searchform.xsd schemas
Name | Description |
---|---|
ObSearchForm |
Describes a search form which consists of zero or more of the following elements: ObHelpContext, ObRequestInfo, ObScripts, ObForm, ObDisplay, ObButton, ObAdvancedSearch, ObSearchRow, and ObStatus. |
ObSearchRow |
Describes each row of the search form, consisting of zero or more ObDisplay elements. The SearchRow contains the information required to output a table row which contains 3 fields: a text box, and two select boxes. |
ObAdvancedSearch |
Indicates if the advanced search capability is enabled through inclusion of and the value set for the optional XML attribute obadvancedSearchOn. |
ObHelpContext |
PC Data containing information about the context of the page, used for online help. |
The searchform.xsd file in WebPass_install_dir
\identity\oblix\WebServices\XMLSchema
contains the elements described in Table 2-16. All elements in this file are in the oblix namespace.
Table 2-16 component_panel.xsd schemas
Name | Description |
---|---|
ObHeaderPanel |
Describes the header panel, which contains a number of LDAP attributes described by zero or more ObAttribute elements. In addition, a panel is described with a number of optional XML attributes, those specified by the administrator during panel configuration in the Identity System Console. A profile page can have a number of panels but only one header panel. |
ObPanel |
Describes a panel, which contains a number of LDAP attributes described by zero or more ObAttribute elements. In addition, a panel is described with a number of optional XML attributes, those specified by the administrator during panel configuration in the Identity System Console. A profile page can have a number of panels but only one header panel. |
The searchform.xsd file in WebPass_install_dir
\identity\oblix\WebServices\XMLSchema
contains the elements described in Table 2-17. All elements in this file are in the oblix namespace.
Oracle Access Manager provides default GIF files used in presenting the page and supports any type of image the browser supports. These are always provided by WebPass as direct responses to browser requests and are located in WebPass_install_dir
\identity\oblix\lang\
langTag
\style0
, as described in "Directory Structure".
Important: Oracle Access Manager relies on these images files and Oracle recommends that you copy the files to your custom directory, make changes, then include the updated copies in stylesheets. See "Customizing Oracle Access Manager". On rare occasions, if your custom image does not appear but the default does, you may need to change the default image. |
Most of the filenames conform to a standard naming convention. Understanding this convention will help you avoid referencing the wrong image in your stylesheets. An image name includes three elements: <ImagePrefix><DescriptiveName><ImageState>. For example:
2FTABgeneratereport2.gif
ImagePrefix: In the previous example, 2FTAB is the ImagePrefix. This part of the GIF image name describes the way in which the image is used. See the following table for a list and description of the various values for the ImagePrefix.
DescriptiveName: In the example, generatereport is the DescriptiveName. This part of the GIF image name is an attempt to provide a user friendly description of the function, tab, content, or navigation feature with which the image is associated.
ImageState: This part of the GIF image name indicates whether the image shows as active or inactive. Active means that the function, tab, content or navigation feature matches what is currently displayed on the page. Inactive means that it does not; the image represents an alternative that could be selected. The images are usually identical, except that the active image is in a darker color. The difference in naming is:
Active Images: ImageState is set to 2 to represent active images.
Inactive Images: ImageState is omitted for inactive images.
The following is an image for 2FTABgeneratereport2.gif. This is the active image.
The following is an image for 2FTABgeneratereport.gif, the inactive image, shown for comparison.
Table 2-18 lists the possible ImagePrefix values for image files:
Table 2-18 ImagePrefix Types
Image Type | ImagePrefix Value | Description |
---|---|---|
Content Buttons |
CBUTTON |
Associated with activities that select certain subsets of the available data, such as selecting a certain user or adding data. |
Content Buttons (Small) |
2CBUTTON |
Smaller versions of the same. |
Content Image |
CIMAGE |
Descriptive images, not associated with a choice. |
Content Tabs |
CTAB |
Used to select major categories of data, such as a group type. |
Content Tabs (Small) |
2CTAB |
Smaller versions of the same. |
Function Tab |
FTAB |
Associated with activities that the user wants the Identity System to perform, such as creating a group, or generating a report. |
Function Tabs (Small) |
2FTAB |
Smaller versions of the same. |
Login Screen Images |
LOGIN |
These are not for customer use. |
Page Navigation |
NAV |
Used to indicate a change to a different screen, usually with no modification to data. |
Page Navigation (Small) |
2NAV |
Smaller versions of the same. |
Most JavaScript files are located as described in "Directory Structure", in WebPass_install_dir
\identity\oblix\lang\shared
.
JavaScript files refer to the jsPathName variable to locate the image directory. For details, see "gifPathName and jsPathName Variables".
Language-specific messages are referred to through variables in message catalog files. See "Changing Message Catalogs and MouseOver Text" a for details.
There are too many JavaScript files to document the content of all of them here. However, this section provides a list of functions and what they do, for some of the most frequently used Javascript files. You may find a function in this Library that you want to use at a non-standard place in the stylesheet, or the function might serve as a starting point for a new one of your own.
Note: Again, Oracle recommends that you retain files in \shared as a reliable default. You may, however, copy the files in \shared to a custom directory, change the content in the copy, then write your stylesheets to include the new JavaScript files and functions. See "Customizing Oracle Access Manager". |
Located in WebPass_install_dir\identity\oblix\lang\shared
, confirm.js includes the functions described in Table 2-19.
Table 2-19 Confirm.js
Function Name | Description |
---|---|
myConfirm |
Takes a message and a URL as arguments. A confirmation window will appear with the message. If the user presses okay the browser takes the user to the URL. |
confirmDelete |
Confirmation of a delete action in the form of a confirmation window appears. If the user presses okay the browser takes the user to another Web page whose href uses most of the href of the original URL, but replaces the program information with the argument URL. |
confirmClear |
Outputs a Windows confirmation box asking if the user wants to clear x where x is the argument name. If so, the browser takes the user to a new URL based on the information provided in the argument URL. |
Located in WebPass_install_dir\identity\oblix\lang\shared, Customizeresults.js includes the functions described in Table 2-20.
Table 2-20 Customizeresults.js
Function Name | Description |
---|---|
configureCustomizeresults FormAndSubmit |
Takes no arguments; validates the browse results columns selected before submitting the form. Validation restrictions include requiring at least one attribute to be selected, no attribute shall be selected twice, and selected attributes must not be separated by blank selections. |
cancelCustomizeresults FormAndSubmit |
Resets the customizeResultsForm such that no validation is performed. |
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Deactivateuser.js includes the functions described in Table 2-21.
Table 2-21 Deactivateuser.js
Function Name | Description |
---|---|
startSearchAndSubmit |
Submit the monitor search form. |
DeactContinueSearch |
Provides the logic for pressing previous/next in the deactivate search results page. The argument subprogram signals whether this is for previous or next. For next, if this is already the last set of search results, an error message pops up saying so. For previous, if this is the first page, an error message indicatse this. |
submitresults |
Submit the deactivate search form with validation. If validation succeeds the function submits the argument URL to the Identity Server. |
toggleselect |
Toggle the search results form checkboxes from false to true. |
sortDeactivatedUsers (sortBy, sortOrder) |
Set the sort information in the deactivate search results page using the argument information. |
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Groupsubscription.js includes the functions described in Table 2-22.
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Helpcommon.js includes the functions described in Table 2-23.
Table 2-23 Helpcommon.js
Function Name | Description |
---|---|
ObHelp |
Build the help URL by appending to the argument helpUrl using the current page's help context. |
SetHelpContext |
Set the help context of the current page using the information provided from the arguments. |
BuildParameter |
Helper function used by ObHelp to build the name value pair parameters into the form &name=value. |
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Horizontalprofile.js includes the functions described in Table 2-24.
Table 2-24 Horizontalprofile.js
Function Name | Description |
---|---|
toggleImage |
Change the image with the argument |
change |
Change the image specified by the arguments oldName, oldIndex to a new image specified by the argument newName, newIndex. |
showPanel |
Show the panel with the argument panel id name newPanel and argument panel id index newPanelIdx. In addition, the function hides the current panel. |
initDynamicAuxClasses |
Initializes the values of valuesOldName. Iterates through the elements in profileForm and stores the values of the named element oldName in the array valuesOldName. The argument oldName is the name of the element that stores the initial state of the set of auxiliary classes prior to the request. (The name used is ObOldAuxClasses). |
diffAuxClassSet |
Determine whether there is a difference in content between firstSet (the first argument) and secondSet (the second argument). Returns true if there is a difference, false otherwise. |
isAuxClassChange |
Determines whether or not a group type has been newly selected or removed. The current state of group types is stored in ObAuxClasses. The initial state is in ObOldAuxClasses. The method iterates over the elements of the profileForm and stores the values of any named newName elements if selected. It stores these values in valuesNewName. The method then compares valuesNewName to valuesOldName. If there is an element in valuesNewName not in valuesOldName or vice versa, then the state of auxiliary classes has changed. This method is used to determine the toggle state of the save image (either 'save' or 'update'). The argument newName is the name of the element that stores the current state of the set of auxiliary classes (the name used is ObAuxClasses). Returns true if there is a change in the state of the selected group types, false otherwise. |
doSaveRequest |
Does the save request action. This action can result in either the data being saved, or a request for the same page, if the user selected auxiliary classes whose attributes are not visible in the display. The argument oldName is the name of the element that stores the original state of the auxiliary classes. The argument newName is the name of the element that stores the current state of the auxiliary classes. The argument saveAction is the name of the action that will result in the entry being saved. The argument moreAction is the name of the action that will result in a request for the same page with new attributes. |
doToggle |
This method toggles the image of the save button if the state of auxiliary classes has changed. It dynamically determines the source of the save button by looking up imageSave in the set of images in the document. It then re-sources the image by assigning a new image source to the save button element. The method looks up the image by comparing the value of its source. The argument oldName is the name of the element that stores the original state of the auxiliary classes. The argument newName is the name of the element that stores the current state of the auxiliary classes. The argument imageSave is the name of the save button image. The argument |
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Misc.js includes the functions described in Table 2-25.
Note: Oracle strongly recommends that you do not change mics.js. This is a system level file. It is contained in almost every style sheet as an include file. Errors in this file will affect most every style sheet that the system uses. This becomes an insidious problem to solve. Custcare will not know if this file has been modified, and indeed, the customer may not know either. Changing this file can cause hidden problems, or problems down the road. |
Table 2-25 Misc.js
Function Name | Description |
---|---|
obDetectBrowser |
Detects the browser version of the client and set the proper variable. |
submitFormAfter Confirm |
Submits the form after the argument confirmation message is displayed. |
submitLoginForm |
Used for submitting the login form. Checks first to ensure the password is entered and then forms the proper URL for the next page - one that will bring the user to the application selected. |
checkPasswordEnterKey |
Enable feature for allowing users to submit the login form when they press enter (or any other event specified in the argument). (For example, use this if you want to submit the login form when the user presses enter). |
onUserType |
For login form, reload the page when the user selects a different user type. |
onApplication |
For login form, if the user selected Publisher and optional authenticated view is disabled, then take the user to Publisher after the application selection. |
setFocusToFirst TextElement |
Set the focus of the argument form to the first element. |
submitForm |
Submit the first form in the page. |
submitSpecifiedForm |
Submit the form whose name is specified in the argument formName. |
submitFormAfterUser Action |
Submit the form with the action equal to the argument form. If the form action is activateForm, then additional confirmation messages will be displayed. |
submitFormCheckProfil eAttributes |
Function used for checking whether the same profile attribute has been selected more than once. The application's logging policy modification screen uses this. |
submitFormCheckCommonLogParams |
Function used for checking whether numeric value is entered for log file maximum size. |
isInteger |
General purpose function to determine if the value entered is an integer. |
IsNumeric |
General purpose function to determine if the value entered is composed of digits. |
isFloat |
General purpose function to determine if the value entered is float. |
isNonNullInteger |
General purpose function to determine if the value entered is composed of integers. The difference between this function and the isInteger function is that this function does NOT return false if the input value is empty. |
sendtotop |
Set the current page to top. |
IsStringOblix Compliant |
Check to make sure the argument element is a non-empty string that does not contain , or ; or \. If it does, then an error message using the argument message is displayed. |
isEmpty |
Check if the argument string is empty or contains white space. |
denyWithAlert |
Display an alert message using the argument message. |
checkAndSubmitForm |
Submit the form if the argument does not equal "login". If the argument equals "passwd", then time out. |
validateInput |
Validate the following inputs: rootDN: ensure it is not empty. ldapRootPasswd: ensure it is not empty. machineNo: ensure it is not empty. portNo: ensure it is an integer. searchBase: ensure it is not empty. If all validation succeeds, pop up a final confirmation box for the change and submit the form. |
validateSearch |
Ensure that the display field record is a valid integer and that it is not empty. |
checkSearchKey |
Submit the form and perform proper validation for the forms deactUserSearchForm, searchForm, ObSearchGroupMembersForm, viewGroupMembers, and monitorsearchform. |
validateSearchAndSubmit |
Used by start search, more fields and less fields in the search functionality to do submit the form. For start search, validation (of the minimum number of characters for the search criteria values) is performed. For more field and less field, calculations of the number of rows required is calculated and then the form is submitted. |
continueSearch |
Used by the next and back buttons in the search functionality to submit the form. For next, it ensures that this is not already the last set of records. For back, it ensures that this is not already the beginning of the records. |
continueSelectorSearch |
Used by selector search next and back buttons. Submit the form after calculating the startFrom value. |
doSearch |
Submit the search form after assigning the proper values for sortBy and sortOrder, which are both provided as input arguments. |
appendElementsTo BackUrl |
Append a set of element_name=value pairs to the backUrl. The argument backUrl is the back URL string. The argument elements is the set of elements to append. |
startTrim |
Trim the beginning whitespace in the argument string. |
endTrim |
Trim the trailing whitespace in the argument string. |
createBackUrl |
Create and return the portion of the back URL that contains the forms elements. Append element/value pairs from all forms in the HTML document including those within layers. |
PersonSelector |
Used to launch the selector. The argument gotoUrl is the (selector) URL we're about to go to. The argument returnUrl is the URL we need to use to get back to the page that invoked the selector. |
QueryBuilder |
Used to launch query builder. The argument gotoUrl is the (selector) URL we're about to go to. The argument returnUrl is the URL we need to use to get back to the page that invoked the selector. |
sendBookmark |
Used for sending the search results as a bookmark. |
validateLicenseKeys |
Ensures that the form values are not empty. If the form values are empty, pops up an error message saying you must enter the license key. |
validateLicenseKeysAnd Submit |
Ensures that the form values (expected to be the license key values) are not empty and then submits the form. |
lostPassword |
Invokes the lost password functionality after ensuring that the login field is not empty. |
certLicenseMessage |
Pops up a message to warn the user to install the certificate management license file before any function is enabled. |
installIECert |
Calls a Virtual Basic Script function to install an x509 certificate. If we are using Netscape, it will contact the common server and get a stream of binary certificate. |
extractCert |
Calls a Virtual Basic Script function to install an x509 certificate. |
performOCSP |
Calls back to the modify profile page to use OCSP (Online Certificate Status Protocol) for certificate online checking. Before the URL is directed, it will pop up an alert to warn the users that the OCSP checking will take a while. |
validateDeactivatedUser Search |
Ensures that the display record for the deactUserSearchForm is a non-empty integer. |
validateGroupMember SearchAndSubmit |
Validates group member search by calling validateGroupMemberSearch. If this is an update member functionality, a pop up message shows to confirm the changes before the form is submitted. |
validateGroupMember Search |
Do validation for group member search, such as ensuring that the minimum number of characters for each search value is satisfied and that the display record is a non-empty integer. |
cancelWorkflow |
Terminate the current workflow. Upon confirmation, go to the argument URL. |
GetCookie |
Retrieve the value of the cookie with the argument name. |
setFocusToOKButton |
Set the focus to the form element that is equal to javascript:top.close() for Internet Explorer 4 and Netscape 6. |
submitFeedBack |
Submit the feedback form. |
checkJavaPlugin |
Check to make sure that the proper java plug-in is installed. |
EnableDetectJava PluginLayer |
Enable the layer called "DetectJavaPlugin". |
EnableJavaPlugin VersionLayer |
Enable the layer called "DetectJavaPluginVersion". |
DetectPluginForApplets |
Verify that Java plug-ins are installed. |
getParameterValue |
Retrieve the value of the parameter in the URL with the argument name. |
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Miscsc.js includes the functions described in Table 2-26.
Important: Oracle strongly recommends that you do not change Miscsc.js. This is a system level file. It is contained in almost every style sheet as an include file. Errors in this file will affect most of the style sheets. This becomes an insidious problem to solve. Support will not know if this file has been modified, and you may not know, either. |
Table 2-26 Miscsc.js
Function Name | Description |
---|---|
SCConfirm |
Submit the profile form. The argument value program will be assigned to the profileForm program field by default or, if an argument message is not empty, then upon confirmation from the user through the pop up confirmation message. |
SCRequestChangeAnd Submit |
Submit the profile form after setting the program field to workflowChangeAttributeRequest. The argument attr determines the attribute for the change attribute request and the argument action determines whether this is a remove or change request. |
SCRequiredValuesAlert |
Provide an alert to the user saying that the required number of values (specified by the argument num_req) for the field ob_name (another argument) is not met. |
SCPasswordNoConfirm |
Alert the user that the password values specified by the argument ob_name do not match. |
SCCheckSingleForm |
Perform validation for each field within the form and alert the user if the validation is not satisfied. Otherwise return true. Sample validation includes checking that password matches, number of required values are met, and so on. |
SCCheckForm |
Check all forms on the page to make sure they satisfy the validation requirements. |
SCSwitchProfile |
Switch between horizontal and vertical modify profile by switching stylesheets. |
SCSubmit |
Submit the form by first performing all the validation. For the different types of actions (for example, save, less_values), additional logic is applied, such as pop up messages displayed and additional information sent back to the Identity Server. |
getElementIndex |
Returns the index of the element elementName in the form, or -1 if elementName is not found. |
CopyElements |
Assigns the value of elements in formFrom to the element of the same name in formTo. |
hasKeyGenForm |
Make sure the NavGenKeyform form is present. |
InvokeKeyGen |
A helper function that submits the NavGenKeyform. |
AppendFormElements |
Appends all the elements from all forms in all layers within the document to the input parameter form. form is in most cases the profileForm which is the form that is submitted. This method assigns the value of each element of each form within each layer to the identically named element in form. This method does not yet handle all special case display types; currently only checkbox is handled. |
Located in WebPass_install_dir
\identity\oblix\lang\shared
, Monitorwf.js includes the functions described in Table 2-27.
Table 2-27 Monitorwf.js
Function Name | Description |
---|---|
startSearchAndSubmit |
Validate the monitorsearchform and then submit it. |
continueSearch |
Called when the user clicks the back and next buttons in monitor search results. If next is pressed, first checks if we are on the last record set, if so signals an error, otherwise, submits the form. If back is pressed, first checks if we are on the first set of records, if so signals that we are already at the beginning, otherwise, submits the form. |
doSearchAndSort |
Called to sort the search results for monitor search results using the arguments sortBy and sortOrder to perform the sorting. |
submitresults |
Called to purge/archive/unlock a workflow. |
toggleselect |
Toggle the search results form checkboxes from false to true. |
For some screens, usually the most basic ones, the URL may not contain the program name. The program name can always be determined by generating and capturing the OutPutXML using format=XML. The stylesheet name will be included, at the top of the resulting file.
Behavior with the result will vary with different versions of Microsoft Internet Explorer. For consistency, use Netscape Communicator and save the output as a text file, using an xml extension. You can then view this file with any text editor to get the stylesheet name.
XSL stylesheets give you the ability to place almost any component or piece of data almost anywhere on a page. This is more of an art than a science, and this Guide does not attempt to give precise instructions for getting the presentation you want. Instead, the following discussions outline the recommended approach for a minor change using the default Classic Style as a foundation.
Task overview: Customizing styles
Complete the "Prerequisites to Customizing Styles".
Review the "Customization Facts".
Review the "Customization Guidelines".
Familiarize yourself with the "Customization Methodology Checklist".
Complete the task "Customizing the Identity System Pages" to gain first-hand experience with customization and testing to debug your process.
See also, Chapter 4, "Modifying Catalog Files".
Be sure to complete the following prerequisites before you start to customize a style. This enables you to keep the original Classic Style (\style0) intact for reference and in case you need to return to it as a last resort.
To prepare to customize styles
As an Identity Administrator, add your own style as described in the Oracle Access Manager Identity and Common Administration Guide.
The original style stays in effect until an Identity Administrator makes your style the new system default.
As an Identity Administrator, select the new style as the default style so that you can see the effect of any changes you make.
Style Updates and Maintenance: Default wrapper files in \style0 and default global stylesheets in \shared are periodically updated to instantiate improvements through patches and product upgrades.
The Release Notes will notify you when such updates occur so you can propagate the changes to your custom styles. You will need to compare the new file with your custom file and propagate any changes to your custom styles. It is risky to overwrite a default style with a customized style that bears the same name.
Be sure to record the changes you make and the files that are involved so you can more quickly update custom stylesheets when you update default styles.
Custom Directory: Stylesheet customization should occur only within your custom directory. Customized stylesheets must reside in your custom directory and relative pointers in all files must point to the files in your custom directory, not to files in \shared.
Registration Files: As discussed in "General Content of Registration Files", a common registration file and each application's registration file contain the names of the stylesheets and schema files needed to present pages for the application. For example, when you look at the User Manager registration file in identity\oblix\apps\userservcenter\userservcenterreg.xml, you can see the application name and the names of the stylesheets the application calls during the completion of various functions.
Also, given the application and the program name, you can locate the corresponding schema file name in the application's registration file.
Oracle recommends that only experienced developers using extreme care consider editing a registration file. Registration files are covered in more detail at "Registration Files".
Pointers: All wrapper files and stylesheets contain pointers as include statements that call another file. Most of these pointers are relative pointers that indicate where within the directory structure the file is without providing an absolute path name.
For example, when you look at the usc_profile.xsl stylesheet called by User Manager functions, you can see that it contains include statements with relative pointers that call the following files:
./basic.xsl
./selectorinfo.xsl
./usc_searchform.xsl
./usc_navbar.xsl
When you change the location of a file (place a copy of a stylesheet in your custom directory for customization), pointers to this file (whether relative or absolute) must be changed to reflect the new location in every file that calls it. All relative pointers in a stylesheet should point to files in your custom directory.
In addition, many stylesheets contain relative pointers to object files. If Oracle Access Manager cannot instantiate an object when the page is loaded, unexpected behavior may result. All relative pointers to object files should be absolute pointers, as discussed in "Editing Stylesheets".
Wrapper Files: Wrapper files include pointers to actual stylesheets in \shared. However, you cannot be assured that a wrapper file will be called before the stylesheet because both the common registration file and the application's own registration file call stylesheets according to an internal ordering. For this reason, all wrapper files in your custom directory must be overwritten by a copy of the corresponding default stylesheet from the \shared directory.
Important: Customizing stylesheets is an iterative process. Attempting to copy the entire contents of \shared into your custom directory at one time will produce an error. |
Rather than copying all stylesheets at once, you start by investigating registration files to learn which functions (programs) call which stylesheets. You then selectively copy base stylesheets and a function-related stylesheet into your custom directory to overwrite their wrapper files, as discussed in "Copying Stylesheets to Your Custom Directory". You then customize and test the style for that function. When this returns satisfactory results you repeat the process to customize another function.
The following guidelines should help ensure a successful customization.
Retain all original files in the \style0 and \shared directories in pristine condition and store them safely for future use. Also, make a backup copy of your customized style files so that patches won't disrupt your customization.
Record all changes you make and the files that are affected.
Customize and test your new styles in a non-production environment before migrating them to your production environment.
Important: Oracle recommends that you do not modify original style files in the \shared or \style0 directories. These may be overwritten by patch updates and product upgrades or you may want to refer to them later. |
When you use only one style, consider breaking the dependence on stylesheets in the \shared directory (again, to prevent patch\release updates to \style0 and \shared from disrupting customizations). This means that no stylesheet in your custom directory should inherit from or reference a stylesheet in \shared or \style0.
When you use multiple custom styles, consider the pros and cons of sharing customizations between multiple custom styles with implementing individual customizations for each custom style. For example:
Two styles that share the same stylesheet: When two custom styles (custom_style1 and custom_style2) can share the same stylesheet you may be tempted to customize the stylesheet in the \shared directory despite the risk of having your custom style overwritten by an updated stylesheet in a product patch or upgrade.
Two individual styles: When two custom styles (custom_style1 and custom_style2) require their individually customized stylesheets you use the standard methodology and overwrite the wrapper files in your custom directory with the corresponding stylesheets in \shared.
Consider using parameter stylesheet files for a custom style collection, rather than using hard-coded values (tab id's, attribute names, table/link properties, and so on); this is similar to how program code is written using header files.
As mentioned earlier, customization is an iterative process and more of an art than a science. This Guide does not attempt to give precise instructions for getting the presentation you want. Instead, this section outlines the recommended approach for a minor change.
Important: Oracle recommends that you focus on stylesheets for one function at a time. Attempting to copy all stylesheets from \shared into your custom style directory will result in an error. |
Table 2-28 Customization Methodology Checklist
Check | Action | Description |
---|---|---|
Add a New Style |
See the Oracle Access Manager Identity and Common Administration Guide for details about adding a style and selecting your new style as the default. |
|
Choose a Function to Customize |
Decide which function you will customize first. Oracle recommends that you customize stylesheets related to one function at a time. |
|
Copy Selected Stylesheets into Your Custom Directory |
Copy selected stylesheets from \shared to your custom directory to overwrite corresponding wrapper stylesheets:
|
|
Customize Stylesheets in Your Custom Directory |
|
|
Record Your Work |
Keep a record of the files you change and the changes you make. |
|
Copy Your Custom Directory Structure to WebPass |
Build a custom directory structure on WebPass and copy customized styles and images into it. Note: On WebPass, stylesheets are used only for client-side processing and are not required for server-side processing. |
|
Test Your Customized Style |
|
|
Customize Another Function |
Repeat this process on a function by function basis:
|
|
Propagate the Customized Style |
When you have copied and customized all stylesheets for the application, copy the custom style directory to all Identity Servers and WebPass hosts in your environment. |
This example shows a method for changing the way a page looks, without changing what it does. The change is a simple font color alteration for a specific page in one application. After making the change you will verify that the change is successful. When you finish this functional customization, you will create the same custom style directory structure on WebPass and copy all image files into it so WebPass can display the appropriate images in response to queries. You then test the implementation.
The following topics demonstrate one sequence in the "Customization Methodology Checklist". You can complete the following procedures to gain first-hand experience:
A prerequisite to customizing a style is to add a style and select the new style as the default, as described in the Oracle Access Manager Identity and Common Administration Guide. The resulting files and file structure provide the foundation for your customization.
Suppose you added a new style named Pastel in a directory named Pastel and requested files be copied from Classic Style (in directory \style0).
To confirm the results of adding a new style
Add a style and select it as the default, as described in the Oracle Access Manager Identity and Common Administration Guide.
New Custom Directory: Oracle Access Manager creates a directory that duplicates \style0 for the default language, English. If you have installed a Language Pack for French, Oracle Access Manager also creates a directory that duplicates \style0 in the French language directory.
Locate your new custom directory.
For example:
Identity_install_dir
\identity\oblix\lang\en-us\Pastel
Identity_install_dir
\identity\oblix\lang\fr-fr\
Pastel
Wrapper Stylesheets: Your custom directory contains wrapper stylesheets that point to actual stylesheets in another directory. If you selected the Classic Style to copy from, your custom directory duplicates the content of the \style0 directory.
Open a wrapper stylesheet in your new custom directory, basic.xsl, and review the files that it includes.
For this example:
Identity_install_dir
\identity\oblix\lang\en-us\
Pastel\basic.xsl
<?xml version="1.0" ?> - <!-- Copyright (c) 1996-2005, Oracle Inc. All Rights Reserved. --> - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/"> <xsl:include href="./style.xsl" /> <xsl:include href="../msgctlg.xsl" /> <xsl:include href="../../shared/basic.xsl" /> </xsl:stylesheet>
The basic.xsl wrapper stylesheet includes the following three files:
style.xsl file in your custom directory
msgctlg.xsl, one directory up from your custom directory (in identity\oblix\lang\en-us)
basic.xsl in identity\oblix\lang\shared
Locate and review the content of the basic.xsl stylesheet in \shared.
For example:
Identity_install_dir\identity\oblix\lang\shared\basic.xsl
<?xml version="1.0" ?> - <!-- Copyright (c) 1996-2002, Oblix Inc. All Rights Reserved. --> - <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:oblix="http://www.oblix.com/"> <xsl:include href="obstringutil.xsl" /> - <!-- xsl:output indent="no"/ --> <xsl:include href="font.xsl" /> <xsl:include href="title.xsl" /> ...
The basic.xsl stylesheet in the \shared directory includes additional files (font.xsl, title.xsl, obstringutil.xsl) and provides templates to define attributes and status and control display information. See "basic.xsl" for more information.
During your customization process, you will copy selected stylesheets from the \shared directory into your custom directory. This will overwrite wrapper files with corresponding stylesheets you can then edit in your custom directory.
New Custom XML Document: In addition to the custom directory structure, when you select the new custom style as the default style, Oracle Access Manager creates an XML document (a duplicate of style0.xml) named after the directory you created.
Locate and open the custom xml document that was created when you added the new style.
For this example:
Identity_install_dir\identity
\oblix\config\style\
Pastel
.xml
<?xml version="1.0" ?> - <ParamsCtlg xmlns="http://www.oblix.com" CtlgName="style0"> - <ValNameList ListName=""> <NameValPair ParamName="styleReady" Value="TRUE" /> </ValNameList> </ParamsCtlg>
This new file, stored with style0.xml, provides the status of your custom style and the location of the original style directory from which wrapper files were copied. For example, if your custom style directory is named Pastel and you copied from Classic Style, the Pastel.xml file is created when you select Pastel as the default style.
You do not need to edit this file. The original style0.xml remains unchanged. Also, there is a .lck version, Pastel.xml.lck, which is a lock file. No other new files are created when you add a new style.
Updated styles.xml: The styles.xml file is updated to include a new NameValPair that provides both the directory and style names you supplied when creating the style.
Locate and open the styles.xml file to confirm it was updated with your new style information.
For example:
Identity_install_dir
\identity\oblix\config\style\styles.xml
<?xml version="1.0" encoding="ISO-8859-1" ?> - <ValNameList xmlns="http://www.oblix.com" ListName="styles.xml"> <NameValPair ParamName="style0" Value="Classic Style" /> <NameValPair ParamName="Pastel" Value="Pastel" /> </ValNameList>
In this example, both the default Classic Style and new custom Pastel style are identified. You do not need to edit this file.
After confirming your custom directory structure, new and updated files, you are ready to choose a function and begin your customization.
The first step in the customization process is to choose a function to customize. For this example, suppose you want to change the font color to red on a specific page of the User Manager without changing anything else.
To identify the function and source information
Log in to the Identity System, as usual.
Navigate to the desired page.
For this example, click:
Identity System Console, User Manager, and then click My Identity
The page appears, as shown in Figure 2-6.
The following information on each Identity System application page is useful for customizing styles:
Application Name: The application name, User Manager, appears on a highlighted tab in the top left area of the screen.
Each application's \bin directory contains the registration file that you need to identify functions. See "Registration Files".
Page Name: The page name, in this example it is My Profile, is the first page that you want to customize so you can see text in a red font color.
Registration File Path: The URL for each page includes a path to the application page, for example, identity\oblix\apps\userservcenter\bin\userservcenter.cgi. You can use this to locate the relevant registration file on the Identity Server.
Function Name: The URL for each page also includes a segment, program=view in this case, that you can use to locate the relevant stylesheet name for the function in the registration file.
Record the required information to assist you during the customization.
For this example:
Application: User Manager
Page: User Profile
Registration File Path: Identity_install_dir
\identity\oblix\apps\userservcenter\bin\
Function: program=view
Once you have identified the function you want to customize, your next task in any customization is to copy relevant stylesheets into your custom directory from the \shared directory. This will overwrite wrapper files in your custom directory with copies of stylesheets you can customize. This also retains the original stylesheets in \shared as well as the original default wrappers in \style0.
Locating and copying relevant stylesheets is an iterative process in itself. In the following procedure you will locate and copy:
Base stylesheets
Stylesheets included in base stylesheets
The specific function-related stylesheet identified for the program in the application's registration file, in this case the stylesheet associated with program=view
Stylesheets included in the function-related stylesheet
Eventually your custom directory will contain all stylesheets, including those identified in the application's registration file and in oblixbasereg.xml. Even if you do not need to edit a stylesheet, it must be copied to your custom directory.
Important: Copying stylesheets is an iterative process that must be done in a selective manner. Attempting to copy all stylesheets from \shared to you custom directory at one time will result in an error. |
To locate and copy relevant stylesheets
Copy the base stylesheets to your custom style directory from \shared to overwrite the default wrappers with stylesheets you can customize.
For example:
Copy from: Identity_install_dir
\identity\oblix\lang\en-us\shared\ basic.xsl, font.xsl, searchform.xsl, navbar.xsl, title.xsl
Copy to: Identity_install_dir
\identity\oblix\lang\en-us\
Pastel
\
This retains the original base stylesheets in \shared as well as the original default wrappers in \style0.
Open each base stylesheet in your custom style directory and locate include statements that point to other stylesheets you need to copy, as well as any style information you need to customize.
For this example, see Table 2-29:
Table 2-29 Base Stylesheet Pointers and Items to Customize
Base Stylesheets in Custom Directory | Pointers to Related Stylesheets and Items to Customize |
---|---|
basic.xsl |
Contains implied relative include pointers to other stylesheets you need in your local custom directory: <xsl:include href="obstringutil.xsl" /> <xsl:include href="font.xsl" /> <xsl:include href="title.xsl" /> Record the names of additional stylesheets you need to copy into your custom directory from \shared. In this case, obstringutil.xsl. |
font.xsl |
Does not contain include pointers to other files. Does contain color information you will customize: <xsl:variable name="subHeadingColor">#006699... <xsl:variable name="contentTitleColor">#000000... <xsl:variable name="contentTextColor">#000000... |
searchform.xsl |
Does not contain include pointers to other files. Does not contain color information you will customize. No changes needed to this stylesheet in your custom directory. |
navbar.xsl |
Does not contain include pointers to other files. Does contain color information you may customize later. |
title.xsl |
Does not contain include pointers to other files. Does contain color information you may customize later. No changes needed to this stylesheet in your custom directory. |
Copy stylesheets included in base stylesheets to your custom directory from \shared.
For this example, obstringutil.xsl:
Copy from: Identity_install_dir
\identity\oblix\lang\en-us\shared\ obstringutil.xsl
Copy to: Identity_install_dir
\identity\oblix\lang\en-us\Pastel\obstringutil.xsl
Record the stylesheets you have copied from \shared to your custom directory so you can track your work.
Locate the required registration files.
For this example, oblixbasereg.xml and userservcenterreg.xml:
Identity_install_dir
\identity\oblix\apps\common\bin\oblixbasereg.xml
Identity_install_dir
\identity\oblix\apps\userservcenter\bin\ userservcenterreg.xml
At some point, you typically need stylesheets included in the common registration file oblixbasereg.xml. However, stylesheets included in oblixbasereg.xml are not needed for this example.
For this example, you need to locate only the function-related stylesheet in the userservcenterreg.xml file.
Open the application's registration file and locate the function-related stylesheet you need.
For this example, locate ObProgram name="view":
<?xml version="1.0" ?> - <ObProgramRegistry> - <ObApplication name="userservcenter"> - <ObProgram name="front"> <ObStyleSheet name="usc_profile.xsl" /> <ObSchema name="usc_front.xsd" /> </ObProgram> - <ObProgram name="commonNavbar"> <ObStyleSheet name="usc_profile.xsl" /> <ObSchema name="usc_front.xsd" /> </ObProgram> ... - <ObProgram name="view"> <ObStyleSheet name="usc_profile.xsl" /> <ObButton name="initiateDeactivateUser" /> - <!-- ObButton name="manageSubscriptions"/ --> <ObButton name="userreactivate" /> <ObButton name="wfTicketDelete" /> <ObButton name="userModify" /> <ObSchema name="usc_profile.xsd" /> </ObProgram> ...
You can see in the registration file that the usc_profile.xsl stylesheet is associated with the function you want to customize (ObProgram name="view"). The usc_profile.xsl stylesheet is also associated with a number of other functions.
Copy the function-related stylesheet, usc_profile.xsl, to your custom style directory from \shared and record the stylesheet name.
For this example:
Copy From: Identity_install_dir
\identity\oblix\lang\en-us\shared\ usc_profile.xsl
Copy To: Identity_install_dir
\identity\oblix\lang\en-us\Pastel\ usc_profile.xsl
Open the function-related stylesheet and locate include statements that point to other stylesheets you need to copy, record any information you need to customize.
For this example, usc_profile.xsl:
Table 2-30 usc_profile.xsl Pointers and Items to Customize
usc_profile.xsl in Custom Directory | Pointers to Related Stylesheets and Items to Customize |
---|---|
usc_profile.xsl |
This main stylesheet for the User Manager includes stylesheets that need to be copied to your custom directory: <xsl:include href="./basic.xsl" /> <xsl:include href="./selectorinfo.xsl" /> <xsl:include href="./usc_searchform.xsl" /> <xsl:include href="./usc_navbar.xsl" /> Note: selectorinfo.xsl, usc_searchform.xsl and usc_navbar.xsl should be copied. Also record pointers to objects that should be customized: <object id="cenroll" classid= ... codebase="../../common/bin/xenroll.cab" /> and <script src="../../common/bin/installCert.vbx" ...
|
Repeat steps to copy relevant stylesheets, then record their names and details you need to change.
For this example:
Copy From:
Identity_install_dir
\identity\oblix\lang\en-us\shared\selectorinfo.xsl
Identity_install_dir
\identity\oblix\lang\en-us\shared\usc_searchform.xsl
Identity_install_dir
\identity\oblix\lang\en-us\shared\usc_navbar.xsl
Copy To:
Identity_install_dir
\identity\oblix\lang\en-us\Pastel\selectorinfo.xsl
Identity_install_dir
\identity\oblix\lang\en-us\Pastel\usc_searchform.xsl
Identity_install_dir
\identity\oblix\lang\en-us\Pastel\usc_navbar.xsl
These stylesheets do not contain include statements, other stylesheet names, nor parameters you need to change.
You have collected, copied, and recorded relevant stylesheets for this example.
After copying relevant stylesheets, you may need to edit them. As described in Table 2-29 the information that needs to be customized for this example includes:
Font colors defined in the base stylesheet font.xsl should be changed to red.
Pointers to objects defined in usc_profile.xsl should change from a relative path to an absolute path.
Note: To help streamline development and testing, consider implementing XSL stylesheet control parameters. See "Caching Considerations". |
To edit stylesheets for a simple font color change
Open the font.xsl stylesheet in your custom directory in a text editor.
For example,
Identity_install_dir
\identity\oblix\lang\en-us\
Pastel
\ font.xsl
Edit the stylesheet to change all colors from the default color to red (FF0000), then save the change.
For example,
Change all Default Font Colors From:
... <xsl:variable name="pageHeaderColor">#006699</xsl:variable> <xsl:variable name="subHeadingColor">#006699</xsl:variable> <xsl:variable name="contentTitleColor">#000000</xsl:variable> <xsl:variable name="contentTextColor">#000000</xsl:variable> and others ...
To Red (#FF0000):
... <xsl:variable name="pageHeaderColor">#FF0000</xsl:variable> <xsl:variable name="subHeadingColor">#FF0000</xsl:variable> <xsl:variable name="contentTitleColor">#FF0000</xsl:variable> <xsl:variable name="contentTextColor">#FF0000</xsl:variable> and others ...
Record your changes to this file.
If you restarted the Identity Server now you would not yet see your changes. This is because you have not yet customized the function-related stylesheet that identifies where to apply the changes.
Edit the basic.xsl stylesheet in your custom directory as follows to add required include statements that were in the original basic.xml (but were lost when you copied over the basic.xsl from the shared folder).
Locate the line containing the following:
<xsl:include href="obstringutil.xsl"/>
Add the following information so that it precedes the line identified in a):
<xsl:include href="./style.xsl" /> <xsl:include href="../msgctlg.xsl" />
Edit the usc_profile.xsl stylesheet in your custom directory to change the relative path to objects, as shown in the following, then save the changes.
For example:
Change From a Relative Path:
- <head> ...<object id="cenroll" classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1" codebase="../../common/bin/xenroll.cab" /> ... <script src="../../common/bin/installCert.vbx" language="VBScript" /> </head>
Change To an Absolute Path:
- <head> ... <object id="cenroll" classid="clsid:43F8F289-7A20-11D0-8F06-00C04FC295E1" codebase="/identity/oblix/apps/common/bin/xenroll.cab" /> ... <script src="/identity/oblix/apps/common/bin/installCert.vbx" language="VBScript" /> </head>
This concludes the specific function-related change for this example.
Ensure that file system access control for new custom style directories and files is set to match the ownership and permissions of \style0.
Restart the Identity Server.
If you log in to the Identity System now and view the My Identity page, you will see the red font color. However, the images supplied by WebPass won't appear until they are included in a corresponding custom style directory structure on the WebPass host.
Images and JavaScript are served by the Web server that the WebPass is installed against, not by the Identity Server. When a style refers to an image, the image is served by WebPass. If the image does not exist in the WebPass file hierarchy, the image will appear as a broken link. To avoid this, you need to create a custom style directory on WebPass and include all images in this structure, whether you are adding new images or using default images.
Copy your custom style directory from the Identity Server to WebPass.
For example:
Copy From: Identity_install_dir
\identity\oblix\lang\en-us\
Pastel
Copy To: Identity_install_dir
\identity\oblix\lang\en-us\
Pastel
Note: Stylesheets are included on WebPass for use with client-side processing only. Stylesheets are not required on WebPass for server-side processing. |
Copy all image files from \style0 on WebPass to your custom directory on WebPass, whether you are using default images or adding new images.
For example:
Copy images From: WebPass_install_dir
\identity\oblix\lang\en-us\style0
Copy images To: WebPass_install_dir
\identity\oblix\lang\en-us\
Pastel
Note: This example does not include new images. Only default images called by the new custom style. If custom images are included, copy those to the custom directory as well. |
Restart WebPass.
You are ready to test your customized style.
You are ready to test your customized style and make any changes needed to achieve satisfactory results.
Note: To help simplify development and testing, you may want to implement XSL stylesheet control parameters, as discussed in"Caching Considerations". You may use an XML editing environment to allow testing stylesheet customizations offline, as discussed in Chapter 7, "Useful Tools". |
If you don't obtain the desired result, check the items in "Troubleshooting Customization Issues".
Log in to the Identity System, as usual.
Navigate to the page you customized.
For example:
Click User Manager, and then click My Identity
Confirm that the font color now displays in red, as shown in Figure 2-7.
When you know your style is working, you can push this out to other Oracle Access Manager systems.
Copy your custom style directory from the Identity Server to all other Identity Servers.
Restart each Identity Server.
Copy your custom style directory from the WebPass host to all other WebPass hosts.
Restart each WebPass.
If you obtain unexpected results, check the following items to ensure that you have completed all tasks correctly.
Have you added a new style and selected this as the default style?
Have you identified and copied relevant stylesheets to your custom directory from \shared (see application and common registration files):
Base stylesheets
Stylesheets included in base stylesheets
The specific function-related stylesheet identified in the application's registration file.
Stylesheets included in the function-related stylesheet?
Relevant stylesheets in the common registration file?
Have you made appropriate changes to stylesheets in your custom style directory?
Relative pointers to stylesheets
Relative pointers that should be absolute pointers to objects
Other customization details
Have you created a duplicate custom style directory structure on WebPass?
Have you copied images to your custom style directory structure on WebPass?
Note: Oracle Access Manager relies on these images. Oracle recommends that you copy the files to your custom directory. On rare occasions that your custom image does not appear but the default does, you may need to change the default image. |
Have you restarted the Identity Server and WebPass?
As discussed elsewhere, multiple languages are available for use with version 7.0 and higher. Messages that were once in stylesheets are language dependent and are now defined separately as variables in message catalogs. The new directory structure consolidates all message catalogs for JavaScript files, XSL, and HTML.
Any language-specific files will be located in \lang\langTag.
Any non-language specific objects are located within \lang\shared.
All the stylesheets have a language-specific wrapper in \lang\langTag\style0 which includes the main language-neutral version stylesheet in \lang\shared. This new wrapper segregates the main stylesheet functionality, which is language independent, from language-specific messages.
Language-specific messages are referred to through variables in message catalog files, as discussed in:
Display names for the Identity applications are stored in the stylesheet. For localization, these display names must be translated for the each language that your organization supports.
For example, the display name User Profile is stored as an XSL variable "MUserProfile" in:
Identity_install_dir
\identity\oblix\lang\en-us\msgctlg.xsl file
The XSL variables are stored in the XSL stylesheet, for example usc_profile.xsl, located in Identity_install_dir
/identity/oblix/lang/shared
.
Store the display name text strings in a separate file as XSL variables.
Reference them in the stylesheet.
To verify that a stylesheet is coded correctly, open it in Internet Explorer. The browser will indicate the line number of any errors in the code.