vignette portaldevguideld1

Vignette Portal

Developers Guide

Version 7.4; LD1

VersionVignette Portal Developers Guide, version 7.4 LiveDocs Update 1 (October, 2008)

Copyright and TrademarksCopyright 1996-2008 Vignette Corporation. All rights reserved. Vignette and the V Logo are trademarks or registered trademarks of Vignette Corporation in the United States and other countries. All other company, product, and service names or brands are the trademarks or registered trademarks of their respective owners.

DisclaimerVignette does not warrant, guarantee, or make representations concerning the contents of this document. All information is provided "AS-IS," without express or implied warranties of any kind including, without limitation, the warranties of merchantability, fitness for a particular purpose, quality, and title. Vignette reserves the right to change the contents of this document and the features or functionalities of its products and services at any time without obligation to notify anyone of such changes.

Send Us Your CommentsIf you have comments or suggestions about this manual, please send them to this address:

[email protected] member of the Publications team will acknowledge your mail as soon as possible. You can also reach us at the following address: Vignette Corporation Publications Department 1301 South MoPac Expressway, Suite 100 Austin, TX 78746 USA

ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Vignette Portal Features and Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal J2EE Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Points of Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing End-user Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integrating Content and Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using and Customizing Vignette Portal Services . . . . . . . . . . . . . . . . . . . . . . Using This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 15 16 17 18 19 21 22

Section I: Portal Site Development1 Vignette Portal Web Site Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25The Site Presentation Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview of a Vignette Portal HTML Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Style Types, Styles, and Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secondary Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal Page Composition: Putting the Pieces Together . . . . . . . . . . . Vignette Portal and Request Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Requests vs. Process Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Design Points for Vignette Portal Site Development . . . . . . . . . . . . . . . . . . . . . .25 26 27 28 30 33 34 34 36 40

2 Controlling Navigation and Appearance with Styles . . . . . . . . . . . . . 41Introduction to Style Types and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Style Type and Style Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Template Header Files for Style Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support Files for Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the Look and Feel of Existing Styles. . . . . . . . . . . . . . . . . . . . . . . . . . Developing Styles and Style Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header Style Type and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 43 43 47 47 49 49

Portal Developers Guide

3

Style Types and Styles for Standard Controls . . . . . . . . . . . . . . . . . . . . . . . . . Navigation Style Types and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chrome Style Type and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Footer Style Types and Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Styles and Style Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uploading the CAR File into Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Style Example: Adding Login Functionality to a Style . . . . . . . . . . . . . . . . . . . . .

50 51 65 71 72 72 75 75 76

3 Controlling Page Structure with Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Introduction to Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Grids Shipped with Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying the Look and Feel of Existing Grids . . . . . . . . . . . . . . . . . . . . . . . . . . Developing Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Custom JSP Tags Used in Grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying a Grid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uploading the CAR File into Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Grid Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79 80 83 84 85 86 86 87 88 88

4 Controlling Functionality with Secondary Pages . . . . . . . . . . . . . . . . 93Introduction to Secondary Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Modifying the Look and Feel of an Existing Secondary Page . . . . . . . . . . . . . . . 95 Secondary Page Types and Secondary Page Instances . . . . . . . . . . . . . . . . . . . . . 96 Secondary Page Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Display Requests and Process Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Actions: Where Secondary Pages Do Processing . . . . . . . . . . . . . . . . . . . . . . . . . 98 Action Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Actions on Secondary Page Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Developing a Secondary Page Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Step 1: Plan Your Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Step 2: Create Any Pre-Display Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Step 3: Create Any Process Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Step 4: Create the Primary JSP File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

4

Contents

Developing a Secondary Page Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Custom Portlet Page Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Display APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customization Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automating the Validation and Population of HTML Forms . . . . . . . . . . . . . . . Step 1: Develop a FormBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Set up the Validation Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3: Add Validation Code to the Primary JSP . . . . . . . . . . . . . . . . . . . . . . Step 4: Develop the Action Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secondary Page Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying a Secondary Page Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying a Secondary Page Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

115 115 117 120 120 121 122 125 135 135 136 137 143

5 Using Cascading Style Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Customizing the Look and Feel of Your Portal. . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal CSS, Themes, and End-User Settings . . . . . . . . . . . . . . . . . . CSS, the Java Portlet Standard, and WSRP . . . . . . . . . . . . . . . . . . . . . . . . . . Working with the Vignette Portal CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HTML Elements Requiring No CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Portal CSS Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How CSS Values Map to Portal Themes and End-User Settings. . . . . . . . . . Customizing the CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overriding the Portal Style Sheet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Style Sheets That Respond to Administrator and End-User Settings . . . . . . . Caching Custom Style Sheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149 150 150 151 151 151 152 153 153 154 155

6 Internationalizing and Localizing Site Components . . . . . . . . . . . . . 157Vignette Portal, I18N, and L10N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Portal Users and Language Preference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Precedence Algorithm for Locale Selection. . . . . . . . . . . . . . . . . . . . . . . . . . Creating I18N Property Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing Localized Values in Component Code. . . . . . . . . . . . . . . . . . . . . . . . Custom JSP Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I18N Format Java Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java Utility Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157 158 158 158 159 160 164 166


5

7 Using the Site Development APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Working with the Request and Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with the Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SessionInfo Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SessionUtils Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Display URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Process URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking a Specific Page by Creating a Page URI . . . . . . . . . . . . . . . . . . . . . Adding Parameters to a URI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Out-of-the-Box Components that Render Portlets . . . . . . . . . . . . . . . . . . . . . Specifying the Portlet to be Rendered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AJAX-Enabling Portal Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Portal and Third-Party AJAX Toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal AJAX Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Writing to the Vignette Portal Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using UIDs and Friendly IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Portal Branding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrieving the Portal Installation Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal Utility Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal Constants and JSP Variables . . . . . . . . . . . . . . . . . . . . . . . . . . .169 170 170 171 172 172 173 173 174 174 175 176 178 178 179 185 186 187 189 190 190 191 191

8 Deploying Site Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Vignette Portal Component Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployment Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uploading Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Downloading Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Archive File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Descriptor File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Component Details for Style Types and Secondary Page Types . . . . . . . . . . Component Details for Styles, Grids, and Secondary Pages . . . . . . . . . . . . . Component Uniqueness and Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193 195 196 197 198 199 201 203 204

6

Contents

Section II: Portlet Development9 Java Standard Portlets and Vignette Portal . . . . . . . . . . . . . . . . . . . . . 209Overview of Vignette Portal and Java Standard Portlets . . . . . . . . . . . . . . . . . . Java Standard Portlet Tag Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Attribute Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling URL Security Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AJAX-Enabling Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSR 168 Specification and AJAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSR 286 Specification and AJAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Portal AJAX Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209 210 210 211 212 212 213 214 214

10 Deploying a Java Standard Portlet into a Portal Instance . . . . . . 219Deployment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Vignette Portal Portlet Packaging Tool . . . . . . . . . . . . . . . . . . . . . . . Using the Vignette Portal Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating an Ant Build File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changes Applied by the Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling Direct Requests to a Portlet Application . . . . . . . . . . . . . . . . . . . . . . .219 221 222 222 223 224

11 Using Portlet Modes and Window States . . . . . . . . . . . . . . . . . . . . . . 225Portlet Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Portlet Window States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BINARY Window State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SOLO Window State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RAW Window State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 226 227 229 231

12 PortalBean Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Java Standard Portlets vs. PortalBean Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal and the PortalBean Framework . . . . . . . . . . . . . . . . . . . . . . . . . Support for Standards-Based Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a URI to Another PortalBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Minimizing Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remote Content APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecation of Administrator PortalBeans . . . . . . . . . . . . . . . . . . . . . . . . . .233 234 234 235 235 236 236


7

Other API Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Name Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AJAX-Enabling PortalBean Portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating AJAX URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performing a Partial Portlet Update from a Link . . . . . . . . . . . . . . . . . . . . . . Performing a Partial View Update from a Form Submission . . . . . . . . . . . . . Uploading a File from a Multipart Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . Auto-Completing a Textbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Handling Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CAR Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSP Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retiring a Prototype PortalBean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

236 237 237 238 239 239 239 240 241 241 242 243

Section III: Portal Services13 Portal Services Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Available Portal Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Storing Data in the MetaStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

14 Users and Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Access APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Group Access APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Guest Access to Components . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Custom Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253 253 255 258 260 260 261 267

15 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269The Vignette Portal Caching System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Passivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributed Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Caching Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269 270 271 271 272

8

Contents

Simplest Case. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Multiple Strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Broadcasting Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a Custom Cache Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

272 274 274 275

16 Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277The Vignette Portal Metrics System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . First-Time Database and Connection Pool Setup . . . . . . . . . . . . . . . . . . . . . . . . Creating an External Metrics Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Database and Connection Pool Properties . . . . . . . . . . . . . . . . . . . . . Creating a Custom Metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a Custom Metric in mbeans.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Custom Metrics Archive Table. . . . . . . . . . . . . . . . . . . . . . . . . . . Using Metrics API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Table Aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metrics Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining the Custom Metric in mbeans.xml . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Custom Metric Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding JSP/Java Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277 278 278 279 280 280 282 283 284 284 285 285 286 286 287 287

17 Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289The Vignette Portal Connection Pooling System . . . . . . . . . . . . . . . . . . . . . . . . Connection Pooling Code Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Initializing a Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Connection Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Support for Oracle LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 290 290 291 294

18 Remote Content Retrieval and Manipulation . . . . . . . . . . . . . . . . . . . 297Retrieving Content from Remote Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inspecting and Altering Proxied Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing the WebConnector 3.0 Portlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . Accessing the Remote Request and Response . . . . . . . . . . . . . . . . . . . . . . . . Using a Custom Authenticator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 298 299 300 302


9

Performing Custom Segmentations and Transformations . . . . . . . . . . . . . . . 302

19 Customizing Federated Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Federated Search Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Repositories and Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Terms and the Common Vocabulary . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Custom Search Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 1: Plan the Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Implement the ISearchConnector Interface . . . . . . . . . . . . . . . . . . . . Step 3: Define the Connectors Search Field Names . . . . . . . . . . . . . . . . . . . Step 4: Create the I18N Property Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 5: Create Component Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 6: Package the Connector for Deployment . . . . . . . . . . . . . . . . . . . . . . Step 7: Test the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305 306 307 308 309 309 310 311 316 317 318 328 331

20 Using the Content Access Management and Indexing APIs . . . 333Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CAM Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Folders and Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Access API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Content Item Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ContentManager Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Utilities and Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing Data Source Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Base Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capability Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing Search Engine Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Indexing Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .333 335 336 336 337 337 338 338 339 339 341 342 342 344 345 347 349 350

10

Contents

API Call Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Search Engine Connector Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . Customizing Content Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 1: Create Custom JSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 2: Create and Upload the CAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 3: Update Portal Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Step 4: Restart the Portal Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

352 353 355 357 366 369 369

21 Developing and Deploying Custom Services . . . . . . . . . . . . . . . . . . 371Services and Vignette Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Developing a Configurable Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ServiceController Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controllable Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Service Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deploying Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the Component Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating the CAR File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Uploading the CAR File into Portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371 372 372 373 374 374 375 376 376 376 386 387

AppendicesA Vignette Portal Custom JSP Tag Reference . . . . . . . . . . . . . . . . . . . . 391Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Web Site Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391 392 392 392 393 393 394 395 395 396 397


11

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Story Publisher PortalBean Portlet Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

397 398 398 399 399 399 400 400 401 402 402 402 402 403 403

B Deployment Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405Component Descriptor Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element. . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detail Elements for Styles, Grids, and Secondary Pages . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detail Elements for Style Types and Secondary Page Types . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detail Elements for Service Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .406 406 408 410 410 410 412 413 414 414 415 415 417 418 419 419 420 420 421

12

Contents

Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Detail Elements for Service Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . Detail Elements for Service Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

421 422 422 423 423 423 424 425 425 426 426 427 428 428 429 429 430 430 431 432 432 433 433 433 434

C Vignette Portal JavaScript Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 435AJAX Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendMultiPartForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . sendURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . appendToHandler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_bwcheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_makeObj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435 435 436 436 437 437 437 437 440


13

_getPageOffsetLeft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . _getPageOffsetTop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Drag-and-Drop Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_scrolldown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_scrollleft . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_scrollright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cm_scrollup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

440 440 441 441 441 441 441 441 443

D Vignette Portal CSS Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447Font and Color Settings in the Administration Consoles . . . . . . . . . . . . . . . . . . Vignette Portal Type Selectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Vignette Portal CSS Classes (Class Selectors) . . . . . . . . . . . . . . . . . . . . . . . . . . Mapping of Theme Settings to CSS Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deprecated Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .447 449 450 464 483

E Compatibility with Version 4.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Secondary Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page Display Secondary Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrade Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JSP Programming Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . I18N . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changes Affecting PortalBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .485 486 486 486 488 489 489 489 490

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

14

Contents

IntroductionSummary: Audience: Topics: Provides an overview of Vignette Portal and of the contents of this guide Web page developers, portlet developers, and Java developers

Vignette Portal Features and Concepts (below) Points of Customization on page 17 Using This Guide on page 22

Vignette Portal Features and ConceptsVignette Portal enables customers to rapidly build, customize, and manage multiple web initiatives across the extended enterprise. Portal ships with all of the capabilities required to begin creating and managing a portal immediately. In addition, web designers and Java developers can customize many of the out-of-the-box Portal features: the look and feel of Portal pages, the functionality available to end users, and the underlying Portal services (such as authentication, metrics, and caching).

Vignette Portal SitesGenerally speaking, a web site refers to all of the HTTP- or HTTPS-accessible URLs (or pages) under a given domain, such as www.company.com. The pages of a web site are typically unified by a common purpose, look and feel (such as fonts, colors, and logos), and navigational elements. A Vignette Portal site is a collection of administrable components that provide look and feel, content, functionality, and navigation structure. Sites are created and administered via the Portal administration consoles. Administrators can share components between sites, thereby reusing functionality, look and feel, and applications. The principal components of sites are portlets (providing pluggable applications), grids (controlling the


15

Vignette Portal Features and Concepts

structure of Portal pages), styles (defining page look and feel), and secondary pages (incorporating functionality into pages). Figure 1 illustrates the relationships among Portal components, Portal sites, and web sites.Figure 1: Portal Components and SitesPortal Site Presentation Framework extranet sitemultiple initiatives

intranet site

Portlets intranet site (a logical object) Grids extranet site (a logical object) Styles corporate site (a logical object) Secondary Pages

corporate site

Vignette Portal J2EE ArchitectureVignette Portal runs within a J2EE application server environment. As Figure 2 shows, multiple J2EE web applications are involved. In addition to the Portal web application, each individual Java standard portlet (JSR 286 application) is deployed as an individual web application.

16

Introduction

Points of Customization

Figure 2:

J2EE Web ApplicationsJ2EE Application Server Vignette Portal (a WAR)

end user

Java Standard Portlet Applications (WARs)

Points of CustomizationVignette Portal supports the following broad categories of configuration and development (see Figure 3): Controlling a sites look and feel and functionality through a site

component architecture Integrating content and applications through portlets Using and customizing Portal services


17

Points of Customizationintranet site

Figure 3:

Portal High-Level ArchitectureSite Presentation Framework

Portal

Site Components grids styles secondary pages

extranet sitemultiple initiatives

Portal Services authentication user management search content management etc.

Portlets

corporate site

Customizing End-user ComponentsThe Portal framework has a component architecture that allows individual pieces of an end-user web site to be customized as needed. Two types of components control the look and feel of the site: grids and styles. Grid and style development requires only JSP scripting skills. No Java skills are needed. Vignette provides custom JSP tags that simplify JSPs by encapsulating portions of the assembly and UI generation logic. A type of component called a secondary page controls the functionality of the site, such as how users log in, how users manage their Portal accounts, and how users select what portlets to view on any given page. Secondary page development often requires only JSP skills, although Java developers can perform deep customizations. End-user components support use of interactive technologies such as AJAX and DHTML. These technologies apply primarily to styles and secondary pages. In addition to supporting third-party and home-grown AJAX wizard toolkits, Vignette Portal provides its own AJAX library. Section I of this guide explains how to customize end-user components.

18

Introduction


Integrating Content and ApplicationsVignette Portal can integrate with portlets, Vignette Builder, .NET technology, and standards-based technologies to provide access to applications and content. Table 1 summarizes how Vignette Portal integrates with various technologies.Table 1: Vignette Portal and Integration Technologies Access to Vignette Portal APIs Limited Java Standard Portlets Full PortalBean Portlets Vignette Builder WSRP Web Service Standards .NET Limited Limited None Limited but extensible Business analyst Variable XML, SOAP, WSDL Visual Studio .NET, VisualBasic Java, JSP, XML Where Application Logic Resides Locally (same VM, different web application) Locally (same VM and web application) Remotely Remotely Remotely Remotely

Technology

Developer Skill Set Java, JSP, XML

Portlets are easily upgradable and personalizable web applications that can be plugged into web sites. They serve as mechanisms for integrating content and applications into a site. Both local, in-process and remote, out-of-process applications and content can be built as portlets. Vignette Portal supports both Java standard portletsthose that conform to the JSR 286 specificationand PortalBean portlets, a Vignette technology that was a precursor to Java standard portlets. (Note that this technology is being deprecated in favor of Java standard portlets.) Portlets of either type can be AJAX-enabled using either Portals own AJAX library or any AJAX widget toolkit. In addition, using the Web Services for Remote Portlets (WSRP) standard, Vignette Portal can consume portlets that are published by WSRP producers. Rather than functioning within the same VM as Portal, WSRP producers can reside in disparate geographical locations, thereby enabling workload to be distributed more easily. (For more about Portal and WSRP interoperability, see Knowledge Base (KB) item 7498.)


19


Section II of this guide provides information about developing Java standard and PortalBean portlets for use with Vignette Portal. Before building a portlet from scratch, consider the no- or low- code alternatives described next.Prebuilt Portlets

Vignette Portal ships with prebuilt portlets that provide a wide range of outof-the-box functionality. These portlets can be added to Portal sites simply by using the Portal administration consoles to instantiate and configure them. Here are a few examples: The Federated Search Portlet can aggregate search results from disparate

sources, such as intranets, public Web sites, and search engines collections. The WebConnector Portlet enables Vignette Portal to proxy content from

external sources. The .NET Integration Portlet exposes a .NET application. The Text Pad portlet displays any amount of HTML or plain-text content;

multiple instances of this portlet can be used to display various kinds of messages.Vignette Builder

Vignette Builder is a WSRP producer whose content can be consumed and surfaced by Vignette Portal. Builder significantly reduces the time and cost of developing, deploying, and managing applications within enterprise portals by empowering non-programmers to build portal applications. By dragging and dropping controls (labels, fields, columns, buttons, and links) in a browser to create forms, reports and charts, application designers can easily construct portal applications. Users can interact with data from disparate applications presented within a single composite web application, controlling both the layout and application flow. Applications can draw on data from relational databases, web services, Vignette IDM, Vignette Records and Documents, and SAP (through the Builder Gateway for SAP). Using the Vignette Business Integration Studio, data from virtually any application or repository (such as Siebel, PeopleSoft, JD Edwards, Lotus Notes/Domino, Artesia, and Microsoft Office) can be transformed into a data source usable by Vignette Builder.

20

Introduction


Builder streamlines portlet development through an intuitive, code-free environment that is seamlessly integrated with Vignette Portal, allowing finished applications to take advantage of Vignette Portal permissions, personalization, and layout flexibility. Application templatespackaged forms, reports, charts, and rules that make up a Builder applicationare available in the Extension Library of the Portal Developer Community of Vignette Connect (http://connect.vignette.com). For convenience, these templates are bundled with a related Portal site.Sample Portlets

The Portal Developer Community of Vignette Connect (http://connect.vignette.com) provides a means to share sample portlets and useful utilities. You can also join the Portal Developer Forum explore ideas and solutions with your peers.

Using and Customizing Vignette Portal ServicesThe Portal framework includes services that perform common portal and web tasks such as authentication, user management, and database connectivity. System administrators can customize a number of services by configuring Vignette Portal, and Java developers can perform deeper customizations by creating their own implementations of certain services. For example, Vignette Portal provides a default SQL user manager, a default SQL authentication implementation, and a default connection pool shared by all Portal data. System administrators can configure Portal to use one of the other shipping user managers (various JNDI implementations) or authenticators (JNDI, NT, and SSO), to change the default connection pool properties, or to configure multiple connection pools. Developers can customize these out-of-the-box services in a number of ways, such as adding fields to the Portal user table and to the Portal page that collects user data, implementing a custom authenticator, and dynamically creating and managing connection pools. Other examples of services are metrics and caching, both of which can be useful in developing portlets and Portal pages. Section III of this guide describes how to use and customize Vignette Portal services. Appendix B, Deployment Reference, provides information about packaging and deploying a custom service for use with Vignette Portal.


21

Using This Guide

Using This GuideThis guide explains how those with web development and Java skills can customize Vignette Portal. Table 2 maps the various development roles to the chapters of this guide that are associated with each.Table 2: Development Roles and Contents of This Guide See

If you want to... customize your Portal installation by modifying the HTML in the end-user JSP files

Modifying the Look and Feel of Existing Styles in Chapter 2, Controlling Navigation and Appearance with Styles Modifying the Look and Feel of Existing Grids in Chapter 3, Controlling Page Structure with Grids Modifying the Look and Feel of an Existing Secondary Page in Chapter 4, Controlling Functionality with Secondary Pages Section I, Portal Site Development (Chapter 1 through Chapter 8) Appendix A, Vignette Portal Custom JSP Tag Reference Chapter 5, Using Cascading Style Sheets Appendix D, Vignette Portal CSS Reference Chapter 6, Internationalizing and Localizing Site Components AJAX-Enabled Navigation Styles and DHTML Navigation Styles in Chapter 2, Controlling Navigation and Appearance with Styles AJAX-Enabling Portal Components in Chapter 7, Using the Site Development APIs AJAX-Enabling Portlets in Chapter 9, Java Standard Portlets and Vignette Portal AJAX-Enabling PortalBean Portlets in Chapter 12, PortalBean Portlets Appendix C, Vignette Portal JavaScript Functions

use JSP to customize your portal use CSS to change the look and feel of enduser Portal pages use the Portal I18N framework add interactive capabilities such as AJAX, JavaScript, or DHTML to Portal components

use Java, XML, and related technologies to customize your portal

All chapters and appendices of this guide

IMPORTANT: Sample code appearing in this guide is not intended to be compiled, executed, or otherwise used. It is included only to support the surrounding text. In many cases, artificial line breaks have been introduced to fit code lines within the margins of this guide. These line breaks often do not conform to proper Java, JSP, XML, CSS, or HTML syntax or conventions.

22

Introduction

Section I: Portal Site Development

1Summary: Audience: Topics:

Vignette Portal Web Site OverviewDescribes the main components of a Vignette Portal site and explains how they interact Web page developers

The Site Presentation Framework (below) Overview of a Vignette Portal HTML Page on page 26 Vignette Portal and Request Handling on page 34 Design Points for Vignette Portal Site Development on page 40

The Site Presentation FrameworkThe site presentation framework of Vignette Portal is responsible for assembling pages for the end user. The framework itself is a set of J2EE filters, servlets, and Java classes that handle such overall tasks as system initialization, authentication, and authorization. Once those tasks are completed, the framework selects the appropriate Portal componentssecondary pages, grids, and stylesto service requests (see Figure 4).


25

Overview of a Vignette Portal HTML Page

Figure 4:

Overview of the Site Presentation Framework

J2EE Application Server Vignette Portal (a WAR) Site Presentation Framework filters servlets classes end user Grids

Styles

Secondary Pages

These components are where the bulk of Vignette Portal site development happens. They are introduced in this chapter and explained in detail in subsequent chapters of this guide.

Overview of a Vignette Portal HTML PageAn HTML page within a Vignette Portal site is composed of regions, such as headers and footers. The regions included on a particular page depend upon its purpose and look-and-feel settings. For example, the login page might have a header, a footer, and a region where the login form is displayed, whereas many pages of a site also have a navigation region (see Figure 5).

26

Vignette Portal Web Site Overview


Figure 5:

Examples of Regions within Portal HTML PagesHeader Page Content

Footer

page with 3 regionsHeader Navigation Page Content

Footer

page with 4 regions

GridsA site component called a grid controls the overall structure of a Vignette Portal HTML page, including the regions that exist on the page. The grid outputs the basic HTML outline of the page, as shown in Figure 6.Figure 6:Grid

Grid with Three RegionsGrid Header Page Content

Footer


27


Grids can define two types of regions (see Figure 7): Regions containing decorative and navigational elements (like headers,

footers, and menus). These elements are called styles. A single region for the primary content/functionality of the page (like login,

user account management, or display of the main view of a Portal site). This functionality is provided by a component called a secondary page. Every grid must include this type of region.Figure 7:Grid Header Page Content

Grid with Two Styles and the Mandatory Secondary Page

style of type "header"

secondary page

Footer

style of type "footer"

See also:

Chapter 3, Controlling Page Structure with Grids, for details about grid development

Style Types, Styles, and ThemesEach type of style corresponds to a Portal component called a style type. A style type can have many different implementations. Each implementation is a Portal component that is simply called a style. Each style provides a different look and feel for a style type. Figure 8 shows three styles of the "header" style type.

28



Figure 8:

Three Implementations of the "Header" Style Type

Basic HeaderGrid Style type: header

Commerce Header

Employee Header

Portal site administrators control the look and feel of their site via themes. A theme specifies one style for every style type in the system, enabling Portal sites to have a unified look and feel. The administrator applies a theme to a particular page or all pages in the site. When a page displays, the region for each style type is fulfilled with a style coming from the theme. In Figure 9, a theme called "basic" contains styles such as the "basic" header, the "basic" footer, etc. An administrator would use this theme to apply the "basic" look and feel to a site or page.Figure 9: "Basic" Theme Applied to a Page with a Header and FooterTheme: "basic" style typeheader navigation site controls footer "basic" header

Grid Style type: header Page Content

style"basic" "basic" "basic" "basic"

Page Content

"basic" footer Style type: footer

See also:

Chapter 2, Controlling Navigation and Appearance with Styles, for details about style and style type development


29


Secondary PagesWhile styles determine the appearance of a page, its functionality is controlled by the secondary page component. Each site function has a corresponding type of secondary page. Here are a few out-of-the-box examples: Login Logout View that displays portlets View that lets a user customize the portlets on a page

Similar to style type and style components, there are secondary page type and secondary page components. Login and logout are examples of secondary page types, and a secondary page type can have multiple implementations, called secondary pages. Secondary page types and secondary pages perform different functional roles: The secondary page type provides the processing logic (via Java classes). A secondary page provides the rendering logic (the JSP) for a particular

secondary page type. This design enables two different appearances to be developed for a particular site function, like the login page, without touching the pages processing logic. A site administrator can use the Portal site console to select the secondary page to be used by the site for each secondary page type.See also: Chapter 4, Controlling Functionality with Secondary Pages, for details about secondary page and secondary page type development

Portlet Pages and JSP Include Pages

Vignette Portal has two other page concepts related to secondary pages: Portlet PageAlso referred to as a portlet display page and simply as a

"page," a portlet page allows administrators to rapidly create and configure portlet-oriented pages, without coding. JSP Include PageThis feature is a quick way to introduce a custom JSP

page into the navigation of a site. Administrators, via the Portal site console, attach portlet pages and JSP include pages to the sites navigation tree, which is a visual representation of

30



the sites menus (see Figure 10). The end-user site displays the navigation via navigation styles (see Figure 11).Figure 10:navigation tree

Navigation Tree with Three Menu Items

Home

Portlet Page X Portlet Page Y Portlet Page Z

Products

Services

Figure 11:

Navigation Tree Rendered by a Navigation Style

Navigation

One secondary page type, called "Page Display," renders portlet pages for display to an end user. This particular secondary page type gets the portlet page that is attached to the currently selected navigation item and renders it. Rendering consists of generating the administrator-specified layout and invoking the portlets within that layout (see Figure 12).


31


Figure 12:

Page Display Secondary Page

Similarly, when custom JSPs are displayed to an end user, there is one particular secondary page type, called "JSP Include Page," that handles invoking the custom JSP. The rendering of portlet pages or JSP include pages can be customized by creating a new secondary page of the Page Display or JSP Include Page secondary page type.Grid Selection

Administrators, via the Portal administration consoles, can select the grid to be used with each secondary page type. Different secondary page types need different grids because different functionality requires inclusion of different style types. For example, the login page does not need the navigation style type: since the user isnt logged in to a site, the sites pages should not be accessible. On the other hand, a user on the main view of a site should be able to navigate that sites pages. Figure 13 illustrates this point.

32



Figure 13:login

Grids for Two Different Secondary Page Typesmain view of portal site style of type "navigation"

Additionally, administrators can select a grid per navigation item within a sites navigation tree. As a result, different portlet pages and JSP include pages within a site can have very different appearances. For example, Figure 14 shows the use of different grids to render the same portlet page with and without vertical navigation.Figure 14: Portlet Page with and without Vertical Navigationmain view with horizontal and vertical navigation style of type "vertical navigation"

main view with horizontal navigation

Vignette Portal Page Composition: Putting the Pieces TogetherHeres the composition process for the login HTML page of a Vignette Portal site:1 2 3 4

A user asks to log into site. Portal retrieves the secondary page of type "login". Portal gets the grid for the secondary page type. Portal renders the grid.


33

Vignette Portal and Request Handling

5 6

The grid applies the appropriate theme (which can be set and overridden at various levels) to get the correct styles. The grid invokes the login secondary page.

Figure 15 summarizes this process. (The details of the process would be a little different if the page requested were part of the navigation tree of a site.)Figure 15: How Vignette Portal Composes a PagePortal 1. Get login secondary page 2. Get grid for login secondary pageStyle type: header Page Content

3. Execute grid, applying theme

end user

asks for login pageStyle type: footer

Vignette Portal and Request HandlingThis section explains how Vignette Portal uses site components to handle requests. It steps through the life of a request and identifies the major touchpoints.

URLsEvery Vignette Portal URL has the following elements in common: protocol, domain name, and port web application context name the constant site followed by the name of the site slashes between elements

34



A URL ending with the site name displays the default page: the first menu item of the navigation tree. In all other cases, the URL includes the remainder of the path information. For a menu item, this path information is either the friendly URI assigned to the menu item, or (if there is no friendly URI) the constant menuitem followed by the menu items unique ID. For a secondary page other than a portlet display page, the path information is the constant template followed by the secondary pages friendly ID. (Note that friendly URIs and friendly IDs are user-assigned values that are mapped internally to unique IDs.) Figure 16 illustrates two URLs: one for a menu item having a friendly URI of products, and the other for the secondary page that enables end users to arrange the portlets on a portlet page.Figure 16: Elements of Vignette Portal URLsdomain name webapp context site name menu item friendly URI

http://mydomain:80/portal/site/mysite/products/port servlet URL sub-components controller (path info)

domain name

webapp context

site name

template friendly ID

http://mydomain:80/portal/site/mysite/template.MOVE_CONTENT/port servlet controller URL sub-components (path info)

Portal administrators can configure the Portal web application to use only the HTTP protocol, to use only the HTTPS protocol, or to select the protocol based on the secondary page. In the selective case, the Portal framework checks whether the current secondary page is configured to be served securely and handles URL generation accordingly.See also:

Vignette Portal Configuration Guide for information about configuring the Portal web application to serve secure requests Vignette Portal Administrators Guide for information about selecting the URL protocol and the security setting for each secondary page


35


Display Requests vs. Process RequestsA request to Vignette Portal can be one of two types: Display requestA request to display something. A display request

returns a page of markup (HTML) to the user. Display requests result in the execution of the entire rendering framework: grid, styles, and secondary page. Process requestA request to process something, like a form submission.

A process request usually ends in a redirect to a display request. Process requests do not execute grids or styles; instead, they execute processing logic contained in the secondary page. Here is how these two request types work together on the login secondary page: A display request to the login secondary page results in a full Portal markup

page being returned, with a login form rendered within it. Clicking the submit button on the login form results in a process request to

the login secondary page. The process request executes the secondary pages processing logic. This logic logs the user in, then redirects the user to the main view of the site (which is a display request). This login scenario, with its display and process requests, is shown in Figure 17.

36



Figure 17:

Login Display and Process RequestsPortal Asks for login screen (a DISPLAY request) Site Presentation Framework Grid Styles Secondary Page Renders login using a grid, styles, and a login secondary page.

end user

Clicks Log In

end user

Submits user name & password (A PROCESS request). Portal Site Presentation Framework Secondary Page Authenticates user, sends redirect for main view of portal.

redirect

browser

Asks for main view (a DISPLAY request)

Portal Site Presentation Framework Grid Styles Secondary Page Renders main view using grid, styles, and page display secondary page.

Display Requests

The processing order in a display request is as follows:


37


1

Portal invokes the secondary pages display actions (which are Java classes; see Chapter 4, Controlling Functionality with Secondary Pages, for documentation of actions). Portal invokes the grid. The grids JSP, via custom Portal JSP tags, invokes the secondary pages JSP as well as the styles (each style contains a JSP).

2 3

Figure 18 shows this control flow.Figure 18: Display Request Control FlowPortal Site Presentation Framework DISPLAY request 1 Secondary Page Process Actions Display Actions JSP Grid 2 JSP Styles JSP 3

end user

An alternative control flow is if a display action detects an error or unusual condition, which results in a redirection. For example, the user might be redirected to an error page. In this case, the grid, the styles, and the secondary page JSP are not invoked. Figure 19 illustrates this alternative control flow.

38



Figure 19:

Display Request Alternative Control FlowPortal Site Presentation Framework DISPLAY request 1 redirect Display Actions JSP Grid JSP Styles JSP Secondary Page Process Actions

end user

Process Requests

Process requests involve secondary pages, grids, and styles working together to service display requests. The processing order in a process request is as follows:1 2

Portal invokes the secondary pages process actions. The last action processed returns a URL to a display request, to which the user is redirected.

Process requests do not invoke the grid, the styles, or the secondary page JSP. Figure 20 shows this control flow.


39

Design Points for Vignette Portal Site Development

Figure 20:

Process Request Control FlowPortal Site Presentation Framework PROCESS request Display Actions Secondary Page 1 Process Actions

end user

JSP

Design Points for Vignette Portal Site DevelopmentAll Vignette Portal site components have access to some commonly used objects and JSP features, including these: A Portal context, which provides access to

The request and response objects Portal-related context about the current request, like the current user Encapsulation of the URL creation logic

A branding object, which provides access to look-and-feel information

from the request: the grid for the request, the secondary page type for the request, fonts, colors, etc. A log object, which supports logging errors and other messages in JSPs Custom JSP tags to do tasks such as internationalization, CSS style block

inclusion, portlet inclusion, and secondary page inclusion User-defined friendly IDs that Portal maps internally to unique identifiersSee also:

Chapter 5, Using Cascading Style Sheets, for discussion of how Vignette Portal uses CSS Appendix A, Vignette Portal Custom JSP Tag Reference, for a list and explanation of all Vignette Portal JSP tags Chapter 7, Using the Site Development APIs, for details about the other features mentioned above

40


2Summary: Audience: Topics: See also:

Controlling Navigation and Appearance with StylesDescribes the various style types and styles within Vignette Portal and explains how to customize them JSP or Java developers responsible for customizing the Vignette Portal end-user site

Introduction to Style Types and Styles (below) Style Type and Style Architecture on page 43 Modifying the Look and Feel of Existing Styles on page 47 Developing Styles and Style Types on page 49 Deploying Styles and Style Types on page 72 Style Example: Adding Login Functionality to a Style on page 76

Chapter 1, Vignette Portal Web Site Overview, for additional discussion of the role of style types and styles within the Vignette Portal presentation framework

Introduction to Style Types and StylesA style type is an abstraction that corresponds to a particular region of a web page, such as the header, the navigation, or the chrome (border, title bar, or other elements displayed with a portlet). A Portal page can have several style types, as shown in Figure 21.


41

Introduction to Style Types and Styles

Figure 21:

Style Types on a Portal PageSite Controls Account Controls Horizontal Navigation Page Controls Chrome Chrome

Header

Vertical Navigation

Chrome

Chrome

Vertical Footer

Each style type can have many styles. A style is an implementation of a style type having a specific appearance and function. Styles control the rendering of their style types portion of a Portal page. The location of each style within a page is determined by the pages grid. (Grids are documented in Chapter 3, Controlling Page Structure with Grids.) A collection of styles that are designed to work together is known as a theme. The Vignette Portal administration consoles can be used to control styles in a variety of ways: For each style type, one style can be selected for use on a particular site or

on all sites. Site and system-wide default styles can be specified for use wherever a

component has not been explicitly associated with a specific style. Themes can be defined that contain collections of styles designed to be

used together. The theme in use can be set at the menu item, site, or server level.See also: Vignette Portal Administrators Guide for details about using the administration consoles to manage style types, styles, themes, and grids

42

Controlling Navigation and Appearance with Styles

Style Type and Style Architecture

Style Type and Style ArchitectureStyle types (as well as secondary page types and the overall collection of grids) are represented by com.epicentric.template.Template objects. Styles (as well as secondary pages and grids) are represented by com.epicentric.template.Style objects. Each Style object is a specific instance of a Template. The Vignette Portal framework handles much of the management of Template and Style objects, including their creation and persistence. You therefore should not need to use many of the methods on these objects directly. Use the Portal administration consoles to add, duplicate, export, import, and delete styles and style types. A style type can include the following files: An optional template header file (template_header.inc), providing

common code that styles of the same style type can use Component descriptor (component.xml file), required to upload the style

type using the deployment system A style consists of the following files: Support files, which include the required primary JSP file and any

secondary files (such as images) that the primary file requires Component descriptor (component.xml file), required to upload the style

using the deployment systemSee also: Chapter 8, Deploying Site Components, for a discussion of component.xml files and the deployment system

Template Header Files for Style TypesEach style type can have a template header file, which contains common logic for some (or all) of the styles of its type. The Vignette Portal convention is to name this file template_header.inc. Template header files prevent code duplication by declaring variables and (in some cases) performing specific functions that primary JSP files can then use. When working with template header files, keep the following caveats in mind: If a variable is declared in the template header file of a style type, do not

declare the same variable in the primary JSP or other support files for styles of that type.


43


Some out-of-the-box styles do not use template header files; others do.

When duplicating a Vignette style as the starting point for your own style, be aware of whether the style uses the template header file. Compilation errors can result if you apply the template header file to a style that was not designed to use it, as well as if you do not apply the template header file to a style that was designed to use it. The value of the apply-templateheader Boolean in a styles component.xml file determines whether that style uses the template header file. Do not reuse code found in template header files shipped with Portal. These

files may use classes and methods that are not part of the Portal published API. Such classes and methods are subject to change between Portal releases. Using them can result in upgrade problems. At minimum, every template header file includes the page import and taglib directives, the custom JSP tag that defines the LOG and portalContext implicit objects, and the declaration of variables: import="javax.servlet.http.*, // ...more packages...

Table 3 describes variables declared in many of the template header files that ship with Portal. (Note that some of the variables declared in template header files are only to support previous Portal versions.)Table 3: Common Variables Declared in Out-of-the-Box Template Header Files

Variable Name adminURL

Description String defining the site administration console link for the current site

44



Table 3: Common Variables Declared in Out-of-the-Box Template Header Files (Continued) Variable Name baseURL Description String concatenating the web application context, the servlet path, and the site name (if any). For example, if the URL is http://mydomain:80/portal/site/sample (where portal is the context, site is the servlet controller, and sample is the site name), the value of this variable is /portal/site/sample. com.epicentric.template.Branding object, used to retrieve the current users font and color preferences Same as baseURL String defining the Add Portlets link for the current page String defining the Site Home link for the current page String identifying the unique ID of the current Style object, used to retrieve the resource bundle for the style String defining the path to the images used in the end-user web site Boolean indicating whether the current site allows visitors (guests) to self-register String defining the Login link for the current site String defining the Logout link for the current site String defining the Arrange Portlets link for the current page com.epicentric.mypage.MyPageList object, containing the list of My Pages for the current user String defining the My Account link for the current user String defining the My Colors link for the current user and current site String defining the friendly ID for the appropriate My Pages secondary page: either "MY_PAGES_DISPLAY" or "MY_PAGES_MANAGE" String defining the My Pages link for the current user

branding controllerURL editContentURL homeURL i18nID imageRoot isSelfRegAllowed loginURL logoutURL moveContentURL mpList myAccountURL myColorsURL myPagesID

myPagesURL


45


Table 3: Common Variables Declared in Out-of-the-Box Template Header Files (Continued) Variable Name Description

pageBackgroundColor String identifying the current users page background color preference _pathToImages pathToStyle portalHttpRoot registerURL sessionInfo String defining the path to the images and other secondary files for the current style String defining the path to the secondary files for the current style (same as _pathToImages) Same as baseURL String defining the Register link enabling guests to selfregister com.epicentric.common.website.SessionInf o object, which contains current user, site, cookies, and other session-related information. com.epicentric.site.Site object, which encapsulates information about the current site Same as adminURL Boolean indicating whether the current user is being authenticated by a single-sign-on product String identifying the value of com.epicentric .common.website.ParameterConstants.SSO (the single-sign-on attribute) com.epicentric.template.Style object for the current style Same as i18nID Same as style String defining the title of the current com.epicentric.template.Style object current com.epicentric.user.User object

site siteConsoleURL SSO SSO_attr

style _thisStyleID _thisStyleObject _thisTitle user

46


Modifying the Look and Feel of Existing Styles

Support Files for StylesEvery style has a primary file, which is a JSP file containing the code needed to execute the style. Any logic that isnt shared with other styles of the same style type goes in the primary file. Such logic includes displaying buttons or links the style is responsible for as well as checking which display elements should be rendered for the current request. When the primary file of a style is first uploaded, the Portal framework checks whether it uses its style types template header file. If so, the framework includes the contents of the header file into the primary file (using the JSP include directive). The resulting file is compiled and executed when the style is called. IMPORTANT: Primary files do not have opening and closing , , or tags. These tags are included by the grid, which in turn includes the style. Styles can also have any number of secondary files. Most commonly, secondary files are image files, but they can also be any other type of file that the primary file requires: CSS, JavaScript, include files, etc. The list of support files for any style can be viewed from the administration consoles (Components >> Style List >> Style Name >> Support Files). You can also use the Support Files page to download and upload custom styles that youve created as well as duplicates of styles that ship with Portal.

Modifying the Look and Feel of Existing StylesYou can customize the physical appearance of an out-of-the-box style simply by editing its primary JSP file. This process does not require Java coding, component deployment, or a Portal application restart. To modify the look and feel of an existing style: 1 2 3

Use a Vignette Portal administration console to duplicate the style that you want to modify (Components >> Styles >> Style List). Select the duplicate from the style list, and use the Support Files tab to download the primary file to your local file system. Make any modifications you wish to your local copy of the primary file. You can change the look and feel by modifying the HTML, CSS, or JavaScript of the file.


47

Modifying the Look and Feel of Existing Styles

4

Use Upload New... on the Support Files tab to upload the modified file into the Vignette Portal installation. IMPORTANT: The upload window includes a check box for indicating whether the template header file should be applied to the primary file youre uploading. An incorrect setting for this check box is likely to cause a compile error when your style is requested. Do not apply the template header file when duplicating any of the following Vignette styles:

Vignette Contemporary DHTML Horizontal Navigation Vignette Contemporary DHTML Vertical Navigation Vignette DHTML Horizontal Navigation Vignette DHTML Vertical Navigation Vignette Linear Nav Horz DHTML Vignette Linear Nav Vert DHTML Vignette Linear Nav Vert Interactive

For all other styles that ship with Portal, apply the template header. To determine whether the template header should be applied to any existing style, export the style, open its CAR file, and check the value of the apply-template-header flag in its component.xml file. If your primary file uses different images or other support files, upload them as well.5

If you want to assign a new name and description to the duplicated style, use the Basics tab. A duplicated component has the same name as the original with (Duplicate) appended. It also has the same description as the original.

Portal administrators can now associate this duplicated style to a theme (Components >> Themes >> Style Name >> Associated Styles). Any Portal page that uses that theme will then use your duplicated style.See also:

Chapter 5, Using Cascading Style Sheets, for information about how Vignette Portal uses CSS Appendix C, Vignette Portal JavaScript Functions, for a list and description of JavaScript functions that ship with Vignette Portal Vignette Portal Administrators Guide for information about using the administration consoles

48


Developing Styles and Style Types

Developing Styles and Style TypesIf you want to customize the appearance of Portal pages, you can create your own implementations of the Portal style types. You can also add functionality that is not provided by any of the Vignette styles by creating custom styles. For example, you might want to incorporate a login field, a search feature, a portlet, or the ability to choose a language within a style. You develop a custom style by creating its primary file and creating any secondary files that it needs. You can use an existing style as the starting point for a new one by duplicating the existing style, exporting it, and modifying the duplicate. In most cases, you do not need to create custom style types; Portal ships with style types for many different regions of a Portal page. Should you need to develop a new style type, simply create a template header file for common variable declarations and other code that styles of the new style type can use. (Of course, youd also need to create styles of your new style type.) The following sections describe the style types and styles that ship with Portal. The end of the chapter explains how to use the deployment system to import custom styles and style types into Portal.See also: Chapter 7, Using the Site Development APIs, for additional component development topics such as AJAX enablement; request, response, and session objects; logging and error APIs; URI generation; and friendly IDs

Header Style Type and StylesThe Header style type defines the area at the top of a Portal page. Styles of this style type usually display the principal branding of the site, such as the site title or an image. Header styles can also include links or buttons for URLs. Most out-of-the-box Header styles simply display the site title, as a localizable string, within the region specified by the grid (see Figure 22). The Vignette Contemporary Header style displays an image that links to the sites "home" URL.


49

Developing Styles and Style Types

Figure 22:Header

Sample Header Style

Style Types and Styles for Standard ControlsThree different style types handle the inclusion of controls that link to basic functions that a portal needs, such as logging in, logging out, personalizing colors, and returning to the main view of a site. These control style types are as follows: Site Controls Links and buttons for using built-in site features, such as

personalizing the site fonts and colors, switching to the site console if the current user is a Portal site administrator, and returning to the "home" page of the site Account Controls User-level links (such as My Pages menu item, login

and logout buttons, self-registration button, and user account maintenance button) and personalized welcome message. (See Style Example: Adding Login Functionality to a Style on page 76 for an example of a custom account controls style.) Page Controls Links for addin