Sc72 Application Developer

8/9/2019 Sc72 Application Developer

1/433

Saba Cloud and Saba Enterprise Release 7.2

Application Developer Guide


2/433

Notice

Limitations on Warranties and Liability

Saba Software, Inc. reserves the right to make changes in information contained

in this document without notice.

In no event shall Saba or its suppliers be liable for any damages whatsoever

(including, without limitation, damages for loss of business profits, business

interruption, loss of business information, or any other pecuniary loss) arising

out of or relating to this documentation or the information contained in it, even

if Saba has been advised of the possibility of such damages and whether arising

from tort (including negligence), breach of contract or otherwise.

This document may only be reproduced and distributed in whole for use by

licensed users. No part of this document may be reproduced in any form for any

other purpose without the prior written consent of Saba Software, Inc.

The software described in this documentation is copyrighted and is confidential

information and a proprietary product of Saba Software, Inc.

U.S. GOVERNMENT RESTRICTED RIGHTS. If licensee is the United States

Government or any contractor thereof, all licenses granted in the License

Agreement accompanying this product are subject to the following: (i) for

acquisition by or on behalf of civilian agencies, as necessary to obtain protection

as "commercial computer software" and related documentation in accordance

with the terms of this Commercial Software Agreement as specified in 48 C.F.R.

12.212 of the Federal Acquisition Regulations and its successors; (ii) for

acquisition by or on behalf of units of the Department of Defense ("DOD") as

necessary to obtain protection as "commercial computer software" and relateddocumentation in accordance with the terms of this commercial computer

software license as specified in 48 C.F.R. 227-7202-2 of the DOD F.A.R.

Supplement and its successors.

Saba, the Saba logo and Centra are registered trademarks of Saba Software, Inc.

and Saba and Saba Centra product names are the trademarks of Saba Software,

Inc. All other product names mentioned in this manual are the property and may

be trademarks or registered trademarks of their respective owners, and are used

for identification purposes only.

© 2013 Saba Software, Inc. All rights reserved.

| Limitations on Warranties and Liab


3/433

| Limitations on Warranties and Liab


4/433

Published: 11/22/2013

Part Number: G-ADG-SCR72000-1

| Introduc


5/433

Contents

Preface: About This Guide..........................................................................................xi

Intended Audience.....................................................................................................................................................xi

How to Contact Saba..................................................................................................................................................xi

Chapter 1: Application Platform Overview..............................................................13

Introduction...............................................................................................................................................................14

System Architecture..................................................................................................................................................14

Security Issues...........................................................................................................................................................15

Internationalization Support......................................................................................................................................15

Multiple Language Support..........................................................................................................................15

Format Localization Support.........................................................................................................................15

Localizable Objects.......................................................................................................................................16

Chapter 2: Customizing Saba....................................................................................17

Introduction to Saba Customizations........................................................................................................................18

UI Configuration: Overview.....................................................................................................................................18

Script Customizations: Overview..............................................................................................................................18

Coding Customizations: Overview...........................................................................................................................19

Chapter 3: WDK Page Tutorial.................................................................................21Overview...................................................................................................................................................................22

Application Page Life Cycle.........................................................................................................................22

Working with WDK Pages............................................................................................................................23

Tutorial Description......................................................................................................................................23

Writing a Simple Portlet...........................................................................................................................................23

First Portlet: "Hello World"...........................................................................................................................24

Following Best Practices: An Improved "Hello World"................................................................................32

Using Widgets...........................................................................................................................................................35

Model File with Widget................................................................................................................................35

View File with Widget...................................................................................................................................37

Command Objects and Visitors.................................................................................................................................38

The Control File............................................................................................................................................39

The Command Object...................................................................................................................................39

Model File with .............................................................................................................44

View File.......................................................................................................................................................48

| T


6/433

Chapter 4: WDK Widgets...........................................................................................49

Widget Overview......................................................................................................................................................51

Using Widgets...........................................................................................................................................................51

Defining in the Model File............................................................................................................................52

Including in the View File.............................................................................................................................57Widget Format...........................................................................................................................................................58

'name' attribute..............................................................................................................................................58

...............................................................................................................................................................58

............................................................................................................................................................58

......................................................................................................................................59

...............................................................................................................................60

...................................................................................................................................................61

Widgets and Model Objects......................................................................................................................................61

The Standard Widget Library....................................................................................................................................62

.......................................................................................................................................66

......................................................................................................................................68

..................................................................................................................................................70

......................................................................................................................................77

..............................................................................................................................81

.........................................................................................................................................84

.................................................................................................................................................89

.......................................................................................................................................................91

.....................................................................................................................................................94

................................................................................................................................................95

.................................................................................................................................................................98

.................................................................................................................................................100

................................................................................................................................................115

..............................................................................................................................................144

............................................................................................................................................................146

...........................................................................................................................................147

................................................................................................................................................149

.................................................................................................................................................150

.................................................................................................................................................153

..................................................................................................................................................154

............................................................................................................................................................155

..................................................................................................................................................161

..............................................................................................................................................................162

...............................................................................................................................................................178

.....................................................................................................................................................184

.....................................................................................................................................................187

................................................................................................................................................188

......................................................................................................................................................190

.....................................................................................................................................................191

| T


7/433

.................................................................................................................................................195

...................................................................................................................................................205

......................................................................................................................................................206

............................................................................................................................................208

...................................................................................................................................................210

......................................................................................................................................................212

...........................................................................................................................................................213............................................................................................................................................................217

........................................................................................................................................................228

.....................................................................................................................................................230

..............................................................................................................................................................232

..........................................................................................................................................257

Component Dictionary Support..............................................................................................................................258

Example..................................................................................................................................................................259

Chapter 5: Model Objects........................................................................................265

Overview.................................................................................................................................................................266

Model Object Lifecycle...........................................................................................................................................266

Defining and Using Model Objects........................................................................................................................267

Declaring a Model Object...........................................................................................................................268

Initializing and Saving/Restoring State...................................................................................................................269

Decoding State............................................................................................................................................270

Encoding State............................................................................................................................................270

Managing Widgets..................................................................................................................................................270

Special WDK Tags..................................................................................................................................................271

getModelObject()....................................................................................................................................................272

..................................................................................................................................................272

Advanced Model Object Techniques......................................................................................................................272

Calling the Model Object From a Second Page..........................................................................................273

Passing Protected State to Another Model Object......................................................................................273

Chapter 6: Coding Customization (Java)................................................................275

Types of Objects......................................................................................................................................................276

Infrastructure Classes..................................................................................................................................276

Class Structure............................................................................................................................................277

Typical Tasks...........................................................................................................................................................280Finding a Specific Reference Object..........................................................................................................280

Finding all objects meeting certain criteria.................................................................................................281

Modifying an Object...................................................................................................................................282

Creating a new object..................................................................................................................................283

Executing Java Code...............................................................................................................................................283

Integrating with WDK pages.......................................................................................................................283

Notification Actions....................................................................................................................................285

| T


8/433

Non-WDK Programming............................................................................................................................285

Chapter 7: Tools and Utilities...................................................................................289

WDK Page Compiler..............................................................................................................................................290

Java ANT Makefile.................................................................................................................................................291

Chapter 8: Designing Portlets..................................................................................293

Overview.................................................................................................................................................................294

Writing a Portlet WDK Page...................................................................................................................................294

Portlet Control Files....................................................................................................................................295

Portlet View Files........................................................................................................................................295

Portlet Model Files......................................................................................................................................296

Links from Portlet Pages.............................................................................................................................296

Testing a Portlet Page..................................................................................................................................296

Coding a Portlet Manager.......................................................................................................................................296

Initializing the Portlet Manager..................................................................................................................296

Registering a Portlet's Page.........................................................................................................................297

Registering Required Parameters................................................................................................................298

Registering Help Pages...............................................................................................................................298

Installing a Portlet...................................................................................................................................................299

Chapter 9: Writing Web Services............................................................................301

Overview.................................................................................................................................................................302

Command Object Requirements.............................................................................................................................302

Generating a WSDL File.........................................................................................................................................304Installing a Custom Web Service............................................................................................................................308

Chapter 10: Localizable Objects..............................................................................309

Chapter 11: WDK Page Tutorial.............................................................................313

Overview.................................................................................................................................................................314

Application Page Life Cycle.......................................................................................................................314

Working with WDK Pages..........................................................................................................................315

Tutorial Description....................................................................................................................................315

Writing a Simple Portlet.........................................................................................................................................315

First Portlet: "Hello World".........................................................................................................................316

Following Best Practices: An Improved "Hello World"..............................................................................324

Using Widgets.........................................................................................................................................................327

Model File with Widget..............................................................................................................................327

View File with Widget.................................................................................................................................329

Command Objects and Visitors...............................................................................................................................330

| T


9/433

The Control File..........................................................................................................................................331

The Command Object.................................................................................................................................331

Model File with ...........................................................................................................336

View File.....................................................................................................................................................340

Chapter 12: Tips and Tricks.....................................................................................341Overview.................................................................................................................................................................342

Making SQL Calls from a Client Command..........................................................................................................342

Using Dynamic Delegates.......................................................................................................................................344

Extending Saba's EJBs............................................................................................................................................345

Extending the Saba EJB..........................................................................................................................................345

Modifying ejb-jar.xml.............................................................................................................................................349

Chapter 13: Sample Java Program..........................................................................353

Sample Code Overview...........................................................................................................................................354

Files.............................................................................................................................................................354

Configuring the Sample Code.....................................................................................................................354

Compiling and Running..............................................................................................................................354

Sample Code Files..................................................................................................................................................355

build.bat.......................................................................................................................................................356

run.bat.....................................................................................................................................................................356

APIExamples.java...................................................................................................................................................358

Chapter 14: Security Configuration........................................................................413

Overview.................................................................................................................................................................414Notes on Saba Configuration..................................................................................................................................414

Special Users...............................................................................................................................................414

Saba J2EE Roles.........................................................................................................................................414

Security.xml................................................................................................................................................415

Login Modules............................................................................................................................................415

Public and Private Keys...............................................................................................................................416

Using Alternate Login Modules..............................................................................................................................416

WebServerSSOLoginModule......................................................................................................................416

LDAPLoginModule....................................................................................................................................416

NTLoginModule.........................................................................................................................................418Using a Third Party Login Module.............................................................................................................418

Writing a Custom Login Module................................................................................................................418

Web Server Single-Sign On....................................................................................................................................418

How It Works..............................................................................................................................................419

Setup and Configuration.............................................................................................................................419

J2EE Single Sign-On..............................................................................................................................................421

Disable Composite Principal.......................................................................................................................421

Add Common Roles to Web Descriptor......................................................................................................421

| T


10/433

Security Constraints....................................................................................................................................422

Chapter 15: Eclipse Plug-in......................................................................................423

Overview and Requirements...................................................................................................................................424

Installing and Configuring the Plug-in....................................................................................................................424

Installing......................................................................................................................................................424Setting Up the Project.................................................................................................................................425

Configuration..............................................................................................................................................426

Editing WDK Pages................................................................................................................................................428

Model Pane..................................................................................................................................................429

Preview Pane...............................................................................................................................................430

Labels View.................................................................................................................................................431

| TO


11/433

Preface

About This Guide

The purpose of this document is to provide the information and guidelines that application developers need to customize

Saba Cloud using Saba's public Java API. The document demonstrates how to customize existing application pages as

well as how to build new pages, taking advantage of the application functionality encapsulated in Saba's Java API.

Intended Audience

This guide is intended for use by the application developers responsible for developing Web applications using Saba's

Web development platform. This document is intended for Saba consultants and for Saba customers. It is also used

internally as a ramping tool for new developers.

The information in this guide assumes you have the following minimum skill set and/or knowledge:

• HTML and JavaScript languages

• Basic familiarity with XML

• Java development

• Standard Web-based GUI, such as Netscape Navigator or Microsoft Internet Explorer

How to Contact Saba

For contact information, see our company Web site: http://www.saba.com.

http://www.saba.com/http://www.saba.com/


12/433


13/433

Chapter

1

Application Platform Overview

This chapter provides an overview of Saba's application development platform.

The chapter describes Saba's system-level architecture and provides detailedTopics:

• Introduction information about Saba's EJB-based application programming model. It alsodescribes security and internationalization issues.• System Architecture

• Security Issues

• Internationalization Support


14/433

Introduction

Saba's application development platform is based on 3-tier distributed object architecture. Saba's 3-tier architecture

comprises the following elements:

•Presentation layer - de

fines the client-side user interface

• Application server layer - handles processing of business logic

• Persistence layer - manages persistent objects in a back-end database

The following diagram illustrates Saba's 3-tier architecture:

Saba's 3-Tier Architecture

The application server includes interfaces for interacting with both the database and the web application page through

the Saba's Java API. The API makes it possible to access and manage business objects while ensuring that securitypermissions and business validations are not violated.

Saba application pages can display application elements to an end-user. They are compiled by the application server

and are designed to be viewed inside a standard Web browser. They enable you to generate content dynamically through

embedded Java statements that access Saba's Java API.

Because presentation logic is separate from business logic, the code designed for displaying information to the end-user

can be separate from code designed for generating data. This separation makes it possible to change one layer without

changing the other.

System ArchitectureSaba's system-level architecture consists of several functional modules layered on top of a set of shared business objects

and core services that provide common application functionality. The functional modules include:

• Learning

• Ordering

• Performance

• Content Management

• Resource Managment

Each functional module includes objects and services specific to the particular application, as well as a set of common

business objects that provide core functionality.

The common business objects layer defines a set of business objects shared across all Saba applications and supports

linkages between the applications.

Supporting the applications and common business objects layers is the core services layer, which provides common

application functionality, including services such as payment processing, business rule configuration, and reporting.

The foundation of Saba's system architecture is the platform layer, which provides the underlying infrastructure for

developing and managing complex enterprise applications. This includes:

• Definition of a core set of abstractions for security, persistence components, and so on, through Saba's Business

Object Server.

| Application Platform Overvi


15/433

• Ability to generate web-based application pages with dynamic content, through Saba's Web Developer Kit.

The layered architecture avoids circular dependencies by requiring that all dependencies be directed downwards. A

vertical application can have dependencies on one or more sets of common business objects but not on other applications.

Similarly, common business objects can depend on core services and on other common business objects, but not on

applications.

This following diagram illustrates Saba's system architecture:

Saba System Architecture

Security Issues

Access to most functionality in a Saba application requires user authentication. A successful login results in a set of

privileges for the individual user in the session environment, along with a session key handle. The privileges take into

account the security roles assigned to the user, as well as any other restrictions associated with the particular environment

or access. Because security in Saba applications is implemented at the business object level, the system checks security

privileges whenever saving or restoring anything to or from the database.

Internationalization Support

Saba enables you to create fully internationalized applications that you can easily localize. Saba's provides support at

the back?end database level for storing locale-specific values.

Multiple Language Support

Saba provides localized versions of its applications for many spoken languages. For each language, the application

interface is fully translated, including all screen text, menus, buttons, messages, and prompts. Online help and selectedproduct documentation are also translated. A single Saba installation can include multiple languages in a single database.

Format Localization Support

In addition to multiple language support, Saba also provides localization formats to fully localize the user experience.



16/433

Localizable Objects

Saba provides the ability to define locale-specific values for some attributes (usually the name and description attributes)

of many objects in the system. When a user defines a value for a localizable object, the system stores the value in a table

specific to the user's locale. Other users who share the locale see this value. However, users with a different locale do

not see this value. Instead, they see only the value entered by users who share their locale.

The only time a user (user "A") belonging to a locale (locale "A") can see the value associated with locale "B" is whenuser "A" retrieves a record that has been created and saved by a user belonging to locale "B".

For a complete list of localizable objects, see Appendix C, "Localizable Objects" Appendix C, "Localizable Objects" on

page C-1.



17/433

Chapter

2

Customizing Saba

Saba provides several ways to customize Saba Cloud, ranging from simple,

application-wide theme changes to intricate customizations written in Java.Topics:

• Introduction to Saba Customizations

• UI Configuration: Overview

• Script Customizations: Overview

•

Coding Customizations: Overview


18/433

Introduction to Saba Customizations

Most customers want to customize Saba Cloud. Some customers make minor changes, such as replacing the Saba logo

with another graphic or changing the color scheme. Other customers make elaborate changes to the way application

pages are displayed or add new functionality to the application pages.

The Saba API makes it possible to customize Saba Cloud in the following ways:

• Con figuration: Settings that affect how the Saba applications run. Most changes here affect all Saba sites running

from a single installation. This includes such operations as changing attribute constraints, custom fields, and business

rules. (These can all be changed with the Saba Administrator UI.) This material is covered in theCatalog Administrator

Guide. It is not further discussed in this book.

• Con figurable UI: This covers look-and-feel options that apply across an entire Saba desktop (a view into a Saba

site). Changes to the UI do not let you modify behavior of specific application pages.

• Scripting: This covers modifications to Saba application pages that do not require coding in Java. This can include

modifying pages to present the same data in different ways, as well as other web-related changes (such as adding

links to other application pages).

• Coding: This covers any customizations that require Java code. This is the most powerful and versatile kind of

customization. Custom Java code can be integrated with Saba application pages, or launched separately.

These options are listed in order of increasing complexity and power. If you have a customization to make, look down

that list and use the first option that works. For example, to change the color scheme for an entire Saba installation, make

a theme customization, perhaps by modifying one of the style sheets.

UI Configuration: Overview

Saba's System Administration screens provide a wide range of UI configuration options. You can easily customize the

system's color schemes, menu configurations, and graphics. You can also set up several different user interface themes

for the same Saba site and make different themes available for different users. For example, you can use one colorscheme for system administrators and another scheme for ordinary users.

For detailed information about the Saba system administration screens, refer to the System Administrator Guide.

Script Customizations: Overview

The Saba engine reads pages written in special script languages, processes them, and generates web pages for users to

view and use. You can modify the application pages' functionality by editing the scripts or creating new script pages.

Application pages are written in the Saba WDK Language, an XML-based language that uses the control/model/view

paradigm to separate data from presentation. This language is described in Chapter 3, "Scripting Customization(WDK)" Chapter 3, "Scripting Customization (WDK)".

Note: Previous Saba releases supported a different kind of application page, called "Saba Pages". In this release,

Saba pages have been entirely superseded by WDK pages.

Saba application pages are written in the WDK Page format. This is an XML-based format for generating application

pages. The page production is separated into separate layers-a model XML file generating the data, a viewfile formatting

the data, and a control page matching up the model file with the view file. This enables developers write application

pages in a modular way. For example, if the same data might be represented in five different formats, developers can

write a single model file and five different view files.

| Customizing Sa

http://-/?-http://-/?-http://-/?-http://-/?-


19/433

Coding Customizations: Overview

Saba provides a Java API that client applications can invoke to retrieve, modify, and delete information from the Saba

data store. This is useful for situations in which other customization options are insuf ficient. For example, you can

change the way a particular application page displays its data by modifying scripts in the existing Saba or WDK pages.

To retrieve data according to your own criteria, you can write custom Java code.

The usual way to invoke Java code is through a Saba application page. There are several ways to do this, for either WDK

pages or Saba script pages. For example, WDK pages provide a tag that invokes a Java command object. When the Saba

engine processes the page, it instantiates the appropriate command object, which in turn generates an XML node. This

XML node is inserted into the model page, making its contents available to any view pages.

In addition, you can write stand-alone Java applications that perform operations on the Saba data store. These applications

could be launched on their own, instead of being integrated with Saba application pages. This is useful for testing -you

can launch portions of your Java code and test them on their own, and integrate the code with the Saba pages after it is

debugged. In addition, there may be times when you want to write a stand-alone application that interacts with the Saba

data store. For example, to perform a large batch operation (such as importing a large amount of data, or making changes

to several records at the same time), write a one-use Java program to perform the operation.

For more information about the Java API, see Chapter 6, "Coding Customization (Java)" Chapter 6, "Coding Customization(Java)".

| Customizing Sa


20/433


21/433

Chapter

3

WDK Page Tutorial

This chapter describes how to write a WDK application page. The chapter covers

a wide range of possible page types, from the very simple to the elaborate.Topics:

• Overview

• Writing a Simple Portlet

• Using Widgets

• Command Objects and Visitors


22/433

Overview

Saba application pages are written in our WDK format. This format is described in detail in Chapter 3, "Scripting

Customization (WDK)" Chapter 3, "Scripting Customization (WDK)". A WDK application page is made of three files:

•The control file is the master

file. It speci

fies the other two

files used by the application page, assigns a uniqueidentifier number to the page, and specifies certain other high-level resources (such as the widget library used by

the page).

• The model file specifies the data displayed in the application page, and also specifies which widgets are available to

the page.

• The view file specifies how the data and widgets are arranged on the application page.

These files are all written in XML. The control file uniquely identifies the application page. That is, by specifying a

control file, you have specified an application page. By contrast, a single model file can be used by several different

application pages. For example, a single model file can present information about users, and several different view files

can present the model file's data in different ways. For example, one view file can display a table with all the data,

another can display only certain columns of the table, and another can display a stripped-down version suitable for

displaying in a portlet.

It is possible to use a single view file with several different model files, but this is far less common than using severalviews with a single model. Usually, a view file is tailored to a specific model file.

Application Page Life Cycle

The life-cycle of a Saba application page is more complex than that of an ordinary web page, and it affects the way Saba

pages are written and maintained.

Each of the three files that make up a Saba application page serves a different function and is used at a different time.

• The model file is compiled to create a Java class. This compilation is done once for each model file. Once the Java

class is created, it can be used every time a user opens an application page which uses that file. The compiled Java

class generates XML output, which contains the data displayed on an application page.• The view file is used to transform the XML output into the web page that is displayed by a user's brower. It produces

a web page with XHTML and Javascript. There is not usually any Java in the output, so the user's browser does not

need to be Java-enabled. (Of course, you could write an application page which runs a Java applet if you wished.)

• The control file identifies the model file and view file used by the application page. When you want to add an

application page into the system, you do it by creating a link (or a menu item) which opens that control file; Saba

then uses the control file to open the view and model file.

Thus, when a user launches an application page, the system follows this sequence of events:

1. The system checks the control file to see what model file and view file are used by the application page.

2. The system checks to see if the model file has already been compiled into a Java class. If it has not, the system

compiles that model file.

3. The system creates a Java object from that class, and uses the object to generate the XML data used by the application

page.

4. The system uses the view file (and any associated stylesheets, like the widget definition stylesheets) to transform

the XML data into an XHTML/Javascript file.

5. The system sends that file to the user's browser, which displays the finished application page.

If the application page is a portal, the system also follows this sequence for each portlet on the page.

The way Saba constructs the finished application page has a few implications you should keep in mind:

• The first time a person runs an application page, Saba has to compile the model file into a Java class. This greatly

slows down the application's response time for that page. The next time anyone views that page (even with different

| WDK Page Tutor

http://-/?-http://-/?-http://-/?-http://-/?-


23/433

data), Saba can use the cached Java class, greatly improving response speed. (You can also use a Saba utility to

compile all the application pages at once, instead of waiting for users to load the pages.)

• When a user views an application page, Saba checks to make sure that the compiled model class is up-to-date. If the

model file is more recent than the Java class, Saba recompiles the class. However , some application servers keep

caches of Java classes used. As a result, if you change a model file while Saba is running, and the model file has

already been used since the last time the application server was launched, the server may use its cached version of

the class instead of the recompiled version based on the new model file. This keeps the changes from showing up

in the compiled application page. For that reason, after you make changes to model files, you may need to restart

your application server to view the changes. (This is not necessary if you make changes to the view or control file.)

Working with WDK Pages

There are two common situations in which one might edit a WDK page.

• You might create a brand-new page entirely from scratch. In that situation, you would need to create a control, model,

and view file, and insert the page into the application.

• You might edit an existing WDK page. In that case, you might duplicate an existing page, modify the duplicate, and

insert the new page into the application. You could also edit the existing page in place.

If you are editing an existing application page, you can ignore much or all of what you see in the files and make a small

alterations. For example, you might decide that a particular table should show less information than it does. You coulddo this by editing the view file to remove a particular column, and not altering the model or control files at all. On the

other hand, if you are creating a new page, you must understand how all three files are constructed, but you might not

need to know subtler details about how the components work. The page that you construct can be simpler than typical

Saba application pages.

Of course, there isn't always a clear line between creating new pages and editing existing ones. Usually when you create

a brand new application page, do it in stages, gradually building up the functionality from one draft of the page to the

next (and borrowing code from existing application pages that do similar things). That is how this tutorial is structured.

It begins by describing how to create a simple portlet, then describes how to add functionality to the portlet, turn it into

an application page, and then add advanced features.

Tutorial Description This tutorial describes how to create a wide number of WDK pages. It shows how to build simple application pages

from scratch, and also how to modify simple pages to create more complex ones.

Note: You may never need to create an entire application page. Usually, you are able to design web pages by

modifying existing WDK application pages.

The tutorial covers the following steps:

• Writing a simple portlet

• Retrieving internationalizable text from Java resources

• Using widgets in application pages

• Using a command object to construct XML data

Writing a Simple Portlet

This section describes how to write a simple Saba portlet. A portlet is a special kind of application page that is designed

to be displayed on a portal page along with other portlets. It is written the same way as any other application page, but

with special restrictions. These are fully detailed in Appendix A, "Designing Portlets" Appendix A, "Designing Portlets",

| WDK Page Tutor


24/433

but portlets should be small, simple, and not make assumptions about how much screen space they can have. This ensures

that Saba can resize the portlet as necessary, and still have it be readable when displayed.

Because a portlet is small and self-contained, and because it is easy to install into Saba, portlets are a very useful way

to design and test WDK functionality. For example, very often the meat of an application page is a table displaying

information. You can build and test that table in a portlet. Then, once that code is working, you can expand it into a full

application page.

This section covers the following steps:

1. Writing a portlet that displays simple text, installing it in Saba, and viewing it.

2. Expanding the portlet to use some common widgets, and to follow Saba's best practices.

First Portlet: "Hello World"

This section describes how to write a simple portlet which displays static text. Needless to say, there are simpler ways

to do this than writing a Saba application page. If you want to write a "message of the day" portlet, you could write it

as an XHTML page. This section describes how to write it as an application page so you can use it as a framework for

more elaborate pages.

Like any other application page, a portlet is made up of three files: a model file containing the data, a view file which

presents the data for display, and a control file which specifies the model and view files, along with some other high-levelinformation. In addition, a portlet requires a special-purpose Java object. For each portlet, you must create and install a

class based on the AbstractPortletPageManager class. This object is used to inform the system where the

control file for the portlet is located. The system can then examine the control file to find the model and view files. (With

a regular application page, the control file is linked to some other way-either through a link widget on some other page,

or by being added to the menu system.)

This section lists typical control, application, and view files, as well as a portlet page manager object which loads the

portlet. The control, model, and view files can be installed anywhere inside the Saba application's document root. In

this example, as is usually the case, the three files are all installed in the same directory. The portlet page manager object

must be compiled, and the class file installed anywhere in the application's Java path.

| WDK Page Tutor


25/433

"Hello World" Control File

The control file specifies the view and model files used by the portlet. Control files vary little from one application page

to the next.

1.0

The bold-face sections are areas you usually would need to change when you create a new control file. In addition, if

the model file contains links to model files (including itself), include a node, as described in

"" "" on page 3-19. Other than that, your various conrol files can all look pretty much the same.

The parts of the control file that might change include:

• Cocoon process type: The


26/433

"Hello World" Model File

The model file contains all the data displayed by the application page or portlet. As noted above, Saba compiles the

model file to create a Java class. It then uses that Java class to generate the XML data for the application page.

In this case, the only data displayed by the page is a simple line of text. To begin with, we hard?code that text into the

portlet. However, as you'll see later in the tutorial, that is not the ideal way to display text in an application page. It is

used here as an example.


27/433

xmlns:xsp="http://www.apache.org/1999/XSP/Core"xmlns:wdktags="http://www.saba.com/XML/WDK/taglib">

com.saba.*

Hello World

Hello, world!

| WDK Page Tutor


28/433

As you can see, this model file contains very little information. The only information specific to the portlet is the text

associated with the hello_text label, "Hello world!"

"Hello,World" View File

The view file is an XSLT stylesheet that transforms the data in the model file into a viewable Saba application page or

portlet. In this case, the view file can be very simple. It displays the text of the model file's hello_text variable in

an XHTML page.


29/433

xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"xmlns:rss10="http://purl.org/rss/1.0/">

The defaultview.xsl file is responsible for creating the general framework of the portlet, including an

node. To fill in the contents of the node, that stylesheet invokes the wdk:model template which you write.

The result is a portlet page containing a single

node, which contains the value of the hello_text variable:

Hello, world!

Note: As noted in Appendix A, "Designing Portlets" Appendix A, "Designing Portlets", a portlet should consist of

either an HTML table (and its contents), or a Saba table widget. Thus, the "Hello, world!" text is put inside an

HTML table with one row and one column.

| WDK Page Tutor


30/433

"Hello,World" Page Manager Object

In order for the application to load the portlet, it must know where the page files are installed. The application finds this

out by instantiating a page manager object specified for the portlet. That object, in turn, registers the control file with

the system.

| WDK Page Tutor


31/433

When you write the portlet page manager, you must know where the application page's control file is installed. (The

Saba application can then examine the control file to find the locations of the model and view files.) In this case, we

assume that the control file is installed as /tutorial/portlet/helloWorldPortlet.rdf .

package com.saba.client.portal;

import com.saba.exception.SabaException;

import com.saba.portal.AbstractPortletPageManager;

import com.saba.portal.PortletPageManager;

/**

*

* This class registers the page for the Hello World portlet.

*

*/

public class HelloWorldPortletPageManager extends AbstractPortletPageManagerimplements PortletPageManager

{

/** The constructor method doesn't need to do anything...*/

public HelloWorldPortletPageManager() {

}

/**

* Initialize the portlet. You must register the portlet by calling

| WDK Page Tutor


32/433

* registerPage.

*/

public void init() throws SabaException {

/* register the control page for this portlet */

registerPage(PortletPageManager.kDefaultDisplay,"/tutorial/portlet/helloWorldPortlet.rdf");

} /* init */

} /* HelloWorldPortletPageManager */

After you compile this class, install it into Saba. Place the class file in the Saba application server's Java class path, then

add the portlet and its manager using the Saba system administration module (as described in the System Administrator

Guide).

Following Best Practices: An Improved "Hello World"

The simple portlet described above shows how to display text, or indeed, to display any xHTML code. However, it does

not follow the WDK's best practices.

As a general rule, you should not hard-code text in your application pages. In the case of the above portlet, the text"Hello, world!" is coded directly into the application page's model file. This makes it dif ficult to internationalize the

portlet if you are providing it to locales which use a different language. Instead of hardcoding text into your application

page, all the text on an application page should be loaded either from internationalizable resources, or from the Saba

application database.

Note: Saba's WDK Eclipse Plug-in provides a feature for editing resource labels, as long as they are named

according to Saba's convention. This tutorial follows that naming convention. In addition, you can use the Eclipse

Plug-in to create the custom labels, and the resource file for them. For more information, see Appendix H, "Eclipse

Plug-in" Appendix H, "Eclipse Plug-in".

Create a normal Java resource bundle for the page's labels. If you wish, this resource bundle can contain versions of the

resources for various locales, or a default version of the resources. Install the resource bundle into the Saba application

server's load path.

| WDK Page Tutor


33/433

Create appropriate resource entries in that resource bundle. In this case, we assume that the resource bundle is named

"my_custom_pages", and we add a single entry to the default resource file:

kI18n511111helloWorldLabel=Hello, world!

Note the naming convention followed. All of an application page's resources should be given names that fit the pattern

kI18n

The model file can then load any resources it needs from that bundle. To use the value of that label, you would change

the model file described above to the following. (Once again, changes are in bold-face.)

com.saba.*

Hello World

| WDK Page Tutor


34/433

| WDK Page Tutor


35/433

When Saba compiles the Java code for the model page, it transforms the node into an

appropriate command to load the text from the resource bundle. Thus, the page uses whatever label is best suited for

the current locale.

The view and control files do not need to be changed to make use of the new label. The view file loads the contents of

the hello_text XML label, as before.

Using Widgets

The previous example showed how to create an application page or portlet which uses straight xHTML. You could use

exactly the same technique to display any other code which is supported by your target browser, such as Javascript or

Java applets.

Saba also provides a powerful library of widgets which you can use in your pages and portlets. There are several

advantages to using widgets:

•The widgets provide a wide range of functionality, including special tools for accessing the Saba data store.

• The Saba application automatically adjusts the widgets to match whatever theme and skin is in use.

• Saba provides a syntax for dynamically creating as many widgets as necessary for the data you want to display. For

example, you might create a page which displays all students in a class, along with a "delete student" button for each

student. In that case, you could define the "delete student" widget once, then use WDK directives to instruct Saba

to create a copy of that widget for each row in the "students enrolled" table.

This section of the tutorial describes how to add a widget to the "Hello World" portlet defined in the previous section.

In this case, the portlet has a single widget, a textArea widget which can be used to display or input text. The following

section describes how to create multiple widgets dynamically to match whatever text your application page may be

displaying.

If you use a widget, you must insert code in two places:

•The model file de

fines the widget itself, specifying what parameters are passed to the widget and how it should bedisplayed.

• The view file specifies where in the file the widget should be displayed.

Model File with Widget

This version of the "Hello, World" portlet displays the text with an input widget. This widget shows a text entry field,

with whatever label you define. The portlet initializes the field with the "Hello, world" message and marks the widget

as view-only.

Widgets are defined in the area of the model file. This version of the model file is exactly like the

one in the previous section, except for that node. (Once again, we assume that the resource bundle and label specified

evaluate to some appropriate text, like "Hello, world!")


36/433


com.saba.*

Hello World

| WDK Page Tutor


37/433

true

As you can see, this version of the portlet no longer has a label. The view file doesn't display the text directly, by accessingthe label. Instead, it displays the helloTextwidget , which contains the message.

View File with Widget

In the earlier version of the "Hello World" portlet, the view file retrieved the text string from the model file, then displayed

that text as HTML. In the new version of the portlet, the view file does not access the text directly. Instead, it contains

a directive to display the widget which contains the text.


38/433

xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"xmlns:rss10="http://purl.org/rss/1.0/">

The bold-faced statement applies the standard Saba widget library's stylesheet to the selected widget. In this case, the

widget is identified by its name, but you could identify the widget by any other XSLT path. For example, you could

search for a widget with a particular ID, or for a widget that's the child of some other node.

Command Objects and Visitors

Unlike application pages that display static content, dynamic pages display information retrieved from the Saba data

store. In some circumstances, you do not even know how much data the page displays. For example, a page written to

display all the goals assigned to students in a class displays no goals if the class has no students or the students have no

goals. If the students have goals, the page can display pages of information.

The WDK enables you to write application pages that dynamically generate their content by executing Java code that

invokes a command object .

A model file is not transformed directly into the application page that users see. Instead, the model file is compiled once

into a special Java class. Then, whenever a user views that application page or portlet, the Java object is created, and it

generates an XML document. The view file, in turn, transforms that created XML document into the application page

or portlet that is shown to the user.

A model file can contain one or more tags. When the model file is compiled, these tags are

turned into Java code that creates a specified Java object, and invokes that object's execute method. That method is

responsible for returning a well-formed XML node. When the model file's object is executed, the

directive is replaced by whatever code is output by the command object.

| WDK Page Tutor


39/433

This example uses a simple command object to generate the XML node. In this example, the command object generates

a static, fixed node, containing data which is displayed in the application page. Of course, the true strength of command

objects is that they can generate their XML output dynamically, and can retrieve information from the Saba data store.

In addition, this application page is designed as a stand-alone page, instead of as a portlet. There is very little difference

between writing a portlet and writing an application page. However, you must add the application page to the Saba

menus, instead of providing a portlet that users can add to their portal pages. For more information about adding new

application pages into the menu system, refer to the System Administrator Guide.

The Control File

The control file for this application page is much like the control file for the portlets described earlier in the tutorial.

1.0

In this case, we assume that the control file is in the same directory as the model and view files, and that all three files

have the root name tutorialCommandPage (with the various appropriate file extensions). We give this application

page the ID number 522222, and designate it as a standalone application page, instead of a portlet.

The Command Object

The core of this new application page is its command object . A model file can run Java code by including a

directive, which is compiled into an instruction to create a particular object and run a particular

method in that object. The directive offers several different calling methods. This example

| WDK Page Tutor


40/433

uses the simplest version of that directive, in which it specifies that a particular command object should be created, and

that command object's execute method should be invoked.

A command object must implement Saba's ICommand interface.Usually, it does this by extending the

AbstractCommand class. If you create a new class based on AbstractCommand, you must provide two methods:

• You must write a no-argument constructor for the object. If the command object expects to be passed parameters,

the constructor method performs some initial processing. If the command object doesn't pass or return parameters,

you can write an empty constructor (as in this example).

• You must write the doExecute method. This method is what generates the XML output. The method does this by

using a visitor . The visitor is a special-purpose object created byAbstractCommand's code, which produces XML

representations of Java objects. If the visitor examines a simple Java type (like a number or a string), it generates an

appropriate XML node. If it visits Saba object which implements IXMLObject, it generates a node for the object,

then recursively visits each field in the object. Thus, if you want to generate an XML representation of some Saba

data, all you usually need to do is create the appropriate Saba object, then pass it to the XML visitor.

| WDK Page Tutor


41/433

In the case of this example, the command object builds its XML output a node at a time, creating a static data set.

/*

* TutorialCommand.java

*

*/

package com.mycorp.tutorial

import java.util.*;

import javax.servlet.http.HttpServletRequest;

import com.saba.web.dk.AbstractCommand;

import com.saba.xml.IXMLVisitor;

import com.saba.xml.SabaXMLType;

/**

* A test command object. It is not passed any parameters. It

* generates the XML output manually.

*

*/

public class TutorialCommand extends AbstractCommand

{

| WDK Page Tutor


42/433

/** Default constructor; doesn't need any code

*/

public TutorialCommand()

{

/* This command object doesn't need any initialization. */

}

/**

* This command generates the output. In this case, it does so

* by using the IXMLVisitor to manually build the output, node

* by node.

*

* This example generates output with the format

*

*

* Smith

* John

*

| WDK Page Tutor


43/433

*

*

*

*/

public void doExecute( HttpServletRequest request,

IXMLVisitor visitor )

throws Exception

{

// Build the XML output node by node.

visitor.beginVisit(null, "people", null, null, null);

visitor.beginVisit(null, "person", null, null, null);

visitor.visit(null, "last_name", "Malfoy");

visitor.visit(null, "first_name", "Draco");

visitor.endVisit(null, "person");


visitor.visit(null, "last_name", "Dumbledore");

visitor.visit(null, "first_name", "Albus");

| WDK Page Tutor


44/433



visitor.visit(null, "last_name", "Weasley");

visitor.visit(null, "first_name", "George");


visitor.endVisit(null, "people");

}

}

This object must be compiled, and the class file placed in your application server's class path.

Model File with

The model file for this example is fairly simple. It is much like the model files used by the portlets earlier in the tutorial.

It has two significant differences:

• Instead of containing the data directly in the file, the model file invokes a command object to generate XML data.

(It uses the command object defined in the last section, TutorialCommand.)

• The model file uses a table widget to display the XML data. The model file attaches the table to the data generated

by the command object, by using a directive. The table widget automatically displays as

many rows as are needed by the data.


45/433


com.saba.*

Test of Command Object


46/433

the command object. -->

First NameLast Name

| WDK Page Tutor


47/433

The directive invokes the command object; as we saw, that object generates the static XML

output

Malfoy

Draco

Dumbledore

Albus

Weasley

George

The model file also specifies that a table widget should be created, and attached to the node. The table

widget specifies that it should have one row for each node under the node. Each row, in turn,

has one column for the first name and one for the last name. The widget thus generates a table like this:

Last NameFirst Name

MalfoyDraco

| WDK Page Tutor


48/433

Last NameFirst Name

DumbledoreAlbus

WeasleyGeorge

Note that the table displays first name before last name, which is different from the order in the command object's output.

When you define the table widget, you are perfectly free to specify what order you want the data to appear in. You can

also choose to omit some of the data returned by your command object. For example, you could easily create a table

which displayed last names.

View File

This view file is very straightforward. All the model file's data is presented in a table widget. The view file needs to

display that widget.

| WDK Page Tutor


49/433

Chapter

4

WDK Widgets

This chapter describes how to use UI widgets in Saba WDK application pages.

The chapter also includes a full reference of available widgets.Topics:

• Widget Overview

• Using Widgets

• Widget Format

• Widgets and Model Objects

•The Standard Widget Library

•

•

•

•

•

•

•

•

•

•

• •

•

•

•

•

•

•

•

•

•

• •

•

•

•

•

•

•

•


50/433

•

•

•

•

•

•

• Component Dictionary Support

• Example

| WDK Widg


51/433

Widget Overview

WDK application pages do not code UI elements (such as menus and buttons) directly. Instead, application pages use

widgets. Widgets are defined in terms of their functionality. For example, instead of using a "text field", a WDK page

uses an input widget . The WDK engine then translates the widget into an appropriate representation for the desired

output format. If the application page is being rendered in HTML, the WDK engine generates appropriate HTMLcomponents. But if, in some future release, other formats are supported (such as WML), the WDK engine could render

the widgets in an appropriate way for that format.

Widgets are used in this way in the WDK:

• The model file defines which widgets are available. It specifies all the contents and attributes of the widgets (such

as the widgets' names and labels). The contents are often set dynamically. For example, a model page might use the

results of an tag to set the contents of a list widget.

• If a WDK page has a model object, Saba queries it for each widget to find out whether the widget is visible. It also

checks to see if the widget is editable and if it should be initialized from the HTTP request that launched the page,

if that is not explicitly specified in the model file.

• The view file specifies how widgets are arranged on the page. It does not need to include all the widgets defined on

the model page. The model might provide a range of widgets, letting the view page choose those that are appropriate.• The control file, besides associating a particular view with a particular model, also specifies an appropriate widget

library file. This file is used by the WDK engine to transform the model page's widget tags into appropriate code

for the target language.

Currently, the only widget library provided is the master widgets file wdk_widgets.xsl. (This master file, in turn,

loads other library files providing various widgets.) This library transforms widgets into HTML UI components. The

widget library is specified in the control file with a tag, which is a child of the

tag:

You add widgets to an application page by adding XML code to the model and view pages. Each widgtet's XML tag

format is defined by an XSLT file. The various widget XSLT files are all included in the library's master WDK widgets

file (wdk_widgets.xsl). This is the file you specify in the application page's control file.

Using Widgets

As noted, if you are using a widget in an application page, you must edit two different files:

• In the model file, you place a full description of the widget. This is an xml node that describes the widget's appearance,

behavior, and so on. The widget may be given a name, and may be attached to a particular XML node.

• In the view file, you put an XML tag specifying where the widget goes. The widget might be identified by its location

(for example, "every link that is attached to a node").

Some widgets can contain other widgets. For example, you might use the table widget to create a table, each of whose

rows has a button (created with the link widget). In that case, you include the container widget in the view file. Saba

builds that widget with all of its contents.

| WDK Widg


52/433

Defining in the Model File

Widgets are defined in the node of the model file (described in Chapter 5, "Model Objects" Chapter

5, "Model Objects"). Each widget may contain special directives that create a connection between the widget itself and

some part of the model. For example, you may want to have an input field whose initial value is determined by some

component of the data model you produced. The directive enables

you to access the value of an XML node in the data model.

| WDK Widg

http://-/?-http://-/?-


53/433

You may also want to associate widgets with data elements in the model object. For example, a particular page might

display a list of people. You might want to create a widget (such as an edit button) for each person in the list. In a

situation like this, the data model produced within might contain a list of person nodes, as follows:

Sam Malone

40

persn00001

Frasier Crane

38

persn0

Documents

Sc72 Application Developer