You are on page 1of 172

Livelink UNITE

Livelink UNITE Widget


Developers Guide
This manual explains how to develop custom
information sources for Livelink UNITE using
the Livelink UNITE Widget Development Kit.
3701910.1
ii
Copyright 2002 by Open Text Corporation. The copyright to these materials and any accompanying software is
owned, without reservation, by Open Text. These materials and any accompanying software may not be copied in whole
or part without the express, written permission of Open Text.
Open Text Corporation is the owner of the following trademarks: BASIS, BASIS Desktop, BASIS Techlib, iRIMS,
Livelink, Livelink Activators, Livelink Change Agents, Livelink Channels, Livelink Collaboration, Livelink Desktop,
Livelink Directory Services, Livelink Discussions, Livelink eLink, Livelink Enterprise Activator, Livelink Explorer,
Livelink Forms, Livelink Intranet, Livelink Library, Livelink LiveReports, Livelink MeetingZone, Livelink Notifications,
Livelink Offline, Livelink OnTime, LiveLink PDF Forms, Livelink Project Collaboration, Livelink Prospectors, Livelink
Remote Cache, Livelink SDK, Livelink Search, Livelink SmartAgent, Livelink Spider, Livelink Tasks, Livelink Workflow,
myLivelink, OnTime, Open Text, and WorkSmart. Other trademarks and trade names in the documentation are
owned by other companies and are used for product and company identification and information only. All rights
reserved. Open Text is the owner of other registered and unregistered trademarks. The above trademark listing is not
exhaustive.
Open Text Corporation provides certain warranties and limitations in connection with the software that this document
describes. For information about these warranties and limitations, refer to the license agreement entered into between the
licensee and Open Text Corporation.
JacORB is included as part of Livelink UNITE. JacORB and its use are covered by the GNU Library General Public
License as published by the Free Software Foundation, either version 2 of the License or (at your option) any later version.
A copy of version 2 of the License is provided when the software is installed. For further information about JacORB, visit
http://www.jacorb.org/.
JSuite tree view copyright 1992-2001 Infragistics, Inc. All rights reserved.
OMG, CORBA, and OMG Interface Definition Language (IDL) are trademarks or registered trademarks of Object
Management Group, Inc. in the United States.
Microsoft, Internet Explorer, MS-DOS, Windows NT, and Windows 2000 are registered trademarks of Microsoft
Corporation in the United States and/or other countries.
Netscape is a registered trademarks of Netscape Communications Corporation in the United States and other countries.
Sun, Sun Microsystems, the Sun logo, Solaris, iPlanet, Java, Java Virtual Machine, and all Java-based marks are
trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
Oracle is a registered trademark of Oracle Corporation.
Written by Paul Mercurio.
Technical reviews by Ann Minton and Scott Carlson.
Contacting Us
Open Text Corporation,
185 Columbia Street West,
Waterloo, Ontario
N2L 5Z5
Canada
(519) 888-7111
If you subscribe to our Customer Assistance Program or would like more information about the support program, visit
Open Text Customer Support at http://www.opentext.com/services/support.html.
If you have suggestions for this publication, send an e-mail message to pubs@opentext.com to contact the Open Text
Publications Group.
Visit our home page at http://www.opentext.com for more information about Open Text products and services.

iii
Typographical Conventions Used in This Guide
All information in the following table is case-sensitive unless otherwise noted.

Items Convention
File names, directory
names, folder names,
path names, window
names, dialog box
names, Web page
names, URLs, and
e-mail addresses
These items appear in regular (normal) typeface. Some
elements in italic indicate placeholders.
Examples:
Run setup.exe to start the installation program.
Open the Livelink_home/config/opentext.ini file in a text
editor.
Note The placeholder Livelink_home represents the
Livelink root directory (directory where Livelink
was installed).
Send an e-mail message to support@opentext.com to contact
Open Text Customer Support.
In the Windows NT Control Panel, double-click the Services
icon to open the Services dialog box.
Names of user
interface elements,
such as buttons, links,
menus, check boxes,
radio buttons, lists,
fields, and so on
These items appear in bold typeface.
Examples:
On the Tools menu, click Search.
In the Services dialog box, click Livelink Server :
service_name, and then click the Start button.
Click the items Functions icon, choose Info, and then choose
General.
Click the Admin Home link.
Variable placeholders,
references to other
documents, new or
special terminology,
and emphasis
These items appear in italic typeface.
Examples:
For more information, see the Livelink First-Time Installation
Guide.
You can scan new documents for content of interest by
saving your search criteria in a query called a prospector.
In your Web browser, go to the default Livelink start page at
protocol://host:port/URL_prefix/livelink.exe, where protocol is
http or https, host is the DNS name of the HTTP server host,
port is the port number on which the HTTP server is
listening, and URL_prefix is the prefix mapped to the
Livelink_home/cgi directory in the HTTP server.
iv
Items Convention
References to chapters
and sections of
documents, and
citations of messages
displayed to users
These items appear in quotation marks.
Examples:
For more information, see Chapter Three, Projects, in the
Livelink QuickStart for Users guide.
For more information, see Item Types in Chapter Five,
Livelink Items.
For more information, see Item Types, page 150.
If the import completes successfully, Oracle displays the
message Database import completed without errors.
Operating system
commands, code
examples, feature
names, method names,
object names, and text
typed by users
These items appear in a monospaced font.
Examples:
In the User Name field, type Admin.
At the operating system prompt, type start-llserver,
and then press ENTER.
When searching for users, you can set the maximum number
of users displayed per page by setting the value (default is
30) of the MaxUsersToListPerPage parameter in the
[general] section of the opentext.ini file.
Key names Key names appear in ALL CAPS.
Examples:
Press ENTER to start a new line when typing in this field.
To select multiple items, hold down the CTRL key while you
click the items that you want to select.
v
Table of Contents
Chapter One
Overview .............................................................................................................................. 1
Livelink UNITE Components ............................................................................................. 2
Widgets..................................................................................................................... 3
Livelink UNITE Extension............................................................................................. 3
Member Requests............................................................................................... 3
Widget Responses .............................................................................................. 4
Member Access ................................................................................................. 4
Front Page Widget ................................................................................................... 4
Profile Data............................................................................................................... 5
Site Profile................................................................................................................. 6
System Profile............................................................................................................ 6
Member Profile......................................................................................................... 7
Naming Service Object............................................................................................ 8
System Log Object ................................................................................................... 9
How Livelink UNITE Processes Requests ......................................................................... 10
Signing In ................................................................................................................ 10
Widget Requests..................................................................................................... 11
Prerequisite Knowledge................................................................................................ 13
Livelink UNITE Interface........................................................................................... 13
Java........................................................................................................................ 13
HTML and JavaScript.............................................................................................. 13
CORBA.................................................................................................................... 14
Interface Definition Language......................................................................... 14
Object Request Broker ..................................................................................... 15
CORBA Resources ............................................................................................ 15
Widget Development Strategy .................................................................................... 16
Determine Widget Architecture....................................................................... 16
Plan Widget Section and Page Features ......................................................... 16
Start Coding/Refer to the Sample Widget ....................................................... 16
Set the Required Widget Property Variables .................................................... 17
Test the Widget................................................................................................. 17
Install the Widget.............................................................................................. 17
vi
Chapter Two
Livelink UNITE IDL Interfaces ................................................................................................ 19
Widgets......................................................................................................................... 20
Widget Architecture......................................................................................... 20
Widget IDL File........................................................................................................ 20
Registering Widgets ................................................................................................ 20
Widget Functions .................................................................................................... 21
Section Rendering ............................................................................................ 21
Page Rendering ............................................................................................... 22
Full-Page View ............................................................................................ 22
Detach-Page View..................................................................................... 22
Configuration Page.................................................................................... 22
Administration Page................................................................................... 23
Widget Online Help ................................................................................................ 23
Custom Help File Location................................................................................ 24
Profiles........................................................................................................................... 25
Profile Structure....................................................................................................... 25
Node Key Path ................................................................................................. 26
Member Profiles ...................................................................................................... 26
Member Profile Structure.................................................................................. 26
Retrieving Member Profile Objects ................................................................... 27
System Profile.......................................................................................................... 27
Retrieving the System Profile............................................................................. 28
Profile IDL File.......................................................................................................... 28
Viewing Profile Contents ........................................................................................ 28
System Log Writer ......................................................................................................... 29
Logging System Information................................................................................... 29
Log Settings ............................................................................................................ 29
Access to the System Log Writer Object ................................................................ 30
Chapter Three
Installing the Widget Developers Kit .................................................................................. 31
Installing the Livelink UNITE WDK on Windows Computers ............................................ 32
Installing the Livelink UNITE WDK on Solaris Computers................................................. 33
vii
Chapter Four
Sample Widgets.................................................................................................................. 35
Overview ...................................................................................................................... 36
Sample Widget Files ............................................................................................... 36
Java Sample Widget Requirements ....................................................................... 36
Java Sample........................................................................................................... 37
Java Sample Widget Files....................................................................................... 37
Build the JBookmark Widget................................................................................... 39
Set the Widget Environment ............................................................................. 39
Compile the IDL ................................................................................................ 39
Compile the JBookmark Java Files................................................................... 40
Copy JBookmark Support Files ......................................................................... 40
Test and Install the JBookmark Widget................................................................... 41
Test JBookmark ................................................................................................. 41
Install JBookmark .............................................................................................. 42
Troubleshooting.......................................................................................... 42
Stop the JBookmark Widget............................................................................. 42
Uninstall the JBookmark Widget ............................................................................. 43
Using the Sample Widget ............................................................................................. 44
Administration................................................................................................... 44
Adding a Section.............................................................................................. 45
Configuration ................................................................................................... 46
Sample Widget Features .................................................................................. 47
Section Statistics ............................................................................................... 48
Chapter Five
Upgrading Custom Widgets................................................................................................ 49
Overview ...................................................................................................................... 50
Upgrading C++ Custom Widgets ........................................................................... 50
Upgrading Custom Widgets from myLivelink 9.0 to Livelink UNITE................................ 51
Convert the Livelink UNITE IDL Files.......................................................................... 51
Recompile Custom Widgets ................................................................................... 51
ORB Modifications .................................................................................................. 51
Upgrading Custom Widgets from a myLivelink Release Pre-9.0 ................................... 52
Upgrading Java Custom Widget Code................................................................. 52
Using the JBookmark Sample Widget............................................................... 52
viii
Code and JavaScript Upgrades ...................................................................... 53
Copy Your Widget Code............................................................................ 53
Profile Operation Data Structure................................................................ 53
System Profile Access ................................................................................. 54
Upgrade Status Methods............................................................................ 54
Exception Message Processing .................................................................. 55
Updated Log Message Format .................................................................. 55
New Notification Types Processing............................................................. 56
Test Your Widget......................................................................................... 57
View Profile Support Upgrades ............................................................................... 58
Suppressing the Section Configuration Button................................................. 58
Retrieving Data for Detached and Full-Page Views ........................................ 59
Accessing the Profile.................................................................................. 59
Passing the Referenced Profile Name........................................................ 59
Action Menu Processing............................................................................. 60
Test Your Widget............................................................................................... 61
JavaScript and Online Help Upgrades ................................................................... 61
JavaScript Modifications ........................................................................................ 61
Including Additional JavaScript Files ................................................................ 61
Setting the Redirect URL ................................................................................... 62
Button Processing ............................................................................................. 62
Administration Pages .................................................................................. 62
Configuration Pages................................................................................... 63
Administration and Configuration Page Descriptions ...................................... 64
Update HTML Form Definitions .......................................................................... 64
New Page_Write () Method.............................................................................. 64
Defining the Section Title Input Box .................................................................. 65
jsQuote and jsString Function Usage................................................................ 65
Choosing a Function .................................................................................. 66
Help File Upgrades.................................................................................................. 68
Chapter Six
Livelink UNITE IDL Reference ............................................................................................... 71
Widget Interface .......................................................................................................... 72
RenderSection.................................................................................................. 73
IDL Syntax ................................................................................................... 73
Parameter .................................................................................................. 73
Exceptions .................................................................................................. 73
ix
RenderPage ..................................................................................................... 74
IDL Syntax ................................................................................................... 74
Parameter .................................................................................................. 74
Return Value............................................................................................... 74
Exception.................................................................................................... 74
StatusGet.......................................................................................................... 75
IDL Syntax ................................................................................................... 75
Parameter .................................................................................................. 75
Return Value............................................................................................... 75
StatusClear ....................................................................................................... 76
IDL Syntax ................................................................................................... 76
Parameter .................................................................................................. 76
Notify ................................................................................................................ 77
IDL Syntax ................................................................................................... 77
Parameter .................................................................................................. 77
Notification Types ....................................................................................... 77
Ping................................................................................................................... 79
IDL Syntax ................................................................................................... 79
Destroy.............................................................................................................. 80
IDL Syntax ................................................................................................... 80
RenderRawPage.............................................................................................. 81
IDL Syntax ................................................................................................... 81
RenderProgressivePage................................................................................... 82
IDL Syntax ................................................................................................... 82
Widget_SectionCallback Interface.............................................................................. 83
RenderSectionCallback ................................................................................... 83
IDL Syntax ................................................................................................... 83
Parameter .................................................................................................. 83
Widget Data Structures ................................................................................................ 84
Section Data Structures .......................................................................................... 85
SectionInfo........................................................................................................ 86
Setting Fields ............................................................................................... 86
IDL Definition............................................................................................... 86
Fields ........................................................................................................... 86
SectionSpec ..................................................................................................... 88
IDL Definition............................................................................................... 88
Fields ........................................................................................................... 88
SectionSize........................................................................................................ 91
IDL Definition............................................................................................... 91
x
Fields ........................................................................................................... 91
Page Data Structures ............................................................................................. 92
PageInfo ........................................................................................................... 93
Setting Fi elds ............................................................................................... 93
IDL Definition............................................................................................... 93
Fields ........................................................................................................... 93
PageInfoButton................................................................................................. 96
IDL Definition............................................................................................... 96
Fields ........................................................................................................... 96
PageInfoButtonSeq .......................................................................................... 97
IDL Definition............................................................................................... 97
PageInfoCookie............................................................................................... 98
IDL Definition............................................................................................... 98
Fields ........................................................................................................... 98
PageInfoCookieSeq ......................................................................................... 99
IDL Definition............................................................................................... 99
PageInfoCookieStatus .................................................................................... 100
IDL Definition............................................................................................. 100
Values ....................................................................................................... 100
PageSpec....................................................................................................... 101
IDL Definition............................................................................................. 101
Fields ......................................................................................................... 101
PageInfoHeaderType..................................................................................... 104
IDL Definition............................................................................................. 104
Values ....................................................................................................... 104
Request Data Structures ....................................................................................... 105
RequestArgs.................................................................................................... 106
IDL Definition............................................................................................. 106
Fields ......................................................................................................... 106
RequestArgsSeq ............................................................................................. 107
IDL Definition............................................................................................. 107
RequestCookie............................................................................................... 108
IDL Definition............................................................................................. 108
Fields ......................................................................................................... 108
RequestCookieSeq ......................................................................................... 109
IDL Definition............................................................................................. 109
Status Data Structures .......................................................................................... 110
Status .............................................................................................................. 111
IDL Definition............................................................................................. 111
xi
Fields ......................................................................................................... 111
StatusSeq ........................................................................................................ 112
IDL Definition............................................................................................. 112
Field .......................................................................................................... 112
General Data Structures ....................................................................................... 113
WStringSeq...................................................................................................... 113
IDL Definition............................................................................................. 113
Widget Exceptions...................................................................................................... 114
WidgetError ..................................................................................................... 114
IDL Definition............................................................................................. 114
Field .......................................................................................................... 114
Livelink UNITE Errors.................................................................................... 114
Java Example........................................................................................... 115
Profile Interface.......................................................................................................... 116
Copy............................................................................................................... 117
IDL Syntax ................................................................................................. 117
Parameters ............................................................................................... 117
Destroy............................................................................................................ 118
IDL Syntax ................................................................................................. 118
KeyGet ........................................................................................................... 119
IDL Syntax ................................................................................................. 119
Parameter ................................................................................................ 119
Return Value............................................................................................. 119
KeyExists .......................................................................................................... 120
IDL Syntax ................................................................................................. 120
Parameter ................................................................................................ 120
Return Value............................................................................................. 120
KeyList ............................................................................................................. 121
IDL Syntax ................................................................................................. 121
Parameter ................................................................................................ 121
Return Value............................................................................................. 121
KeyListSort ....................................................................................................... 122
IDL Syntax ................................................................................................. 122
Parameters ............................................................................................... 122
Return Value............................................................................................. 122
Modify............................................................................................................. 123
IDL Syntax ................................................................................................. 123
Parameter ................................................................................................ 123
Java Example........................................................................................... 123
xii
NameGet ....................................................................................................... 124
IDL Syntax ................................................................................................. 124
Return Value............................................................................................. 124
NKeys .............................................................................................................. 125
IDL Syntax ................................................................................................. 125
Parameter ................................................................................................ 125
Return Value............................................................................................. 125
NProperties ..................................................................................................... 126
IDL Syntax ................................................................................................. 126
Parameter ................................................................................................ 126
Return Value............................................................................................. 126
PropertyAuthenticate..................................................................................... 127
IDL Syntax ................................................................................................. 127
Parameters ............................................................................................... 127
Return Value............................................................................................. 127
PropertyExists .................................................................................................. 128
IDL Syntax ................................................................................................. 128
Parameters ............................................................................................... 128
Return Value............................................................................................. 128
PropertyGet.................................................................................................... 129
IDL Syntax ................................................................................................. 129
Parameters ............................................................................................... 129
Return Value............................................................................................. 129
PropertyGetDecrypt....................................................................................... 130
IDL Syntax ................................................................................................. 130
Parameters ............................................................................................... 130
Return Value............................................................................................. 130
PropertyGetDefaulted.................................................................................... 131
IDL Syntax ................................................................................................. 131
Parameters ............................................................................................... 131
Return Value............................................................................................. 131
PropertyList ..................................................................................................... 132
IDL Syntax ................................................................................................. 132
Parameter ................................................................................................ 132
Return Value............................................................................................. 132
PropertyListNoDefault ..................................................................................... 133
IDL Syntax ................................................................................................. 133
Parameter ................................................................................................ 133
Return Value............................................................................................. 133
xiii
SectionGet ..................................................................................................... 134
IDL Syntax ................................................................................................. 134
Parameter ................................................................................................ 134
Return Value............................................................................................. 134
Profile Data Structures ................................................................................................ 135
ProfileValue .................................................................................................... 136
IDL Definition............................................................................................. 136
Fields ......................................................................................................... 136
ProfileValueSeq .............................................................................................. 137
IDL Definition............................................................................................. 137
ProfileOperation ............................................................................................. 138
IDL Syntax ................................................................................................. 138
Fields ......................................................................................................... 138
ProfileOperationSeq ....................................................................................... 139
IDL Definition............................................................................................. 139
Field .......................................................................................................... 139
ProfileChild...................................................................................................... 140
IDL Definition: ............................................................................................ 140
Fields ......................................................................................................... 140
ProfileChildSeq ............................................................................................... 141
IDL Definition............................................................................................. 141
ProfileSection.................................................................................................. 142
IDL Definition............................................................................................. 142
Fields ......................................................................................................... 142
OperationType ............................................................................................... 143
IDL Definition............................................................................................. 143
Values ....................................................................................................... 143
Profile Exceptions........................................................................................................ 145
ProfileCannotRemoveRoot ............................................................................ 145
System Log Writer Interface........................................................................................ 146
System Log Writer IDL File...................................................................................... 146
Append .......................................................................................................... 147
Parameter ................................................................................................ 147
AppendAsSender ........................................................................................... 148
Parameters ............................................................................................... 148
xiv


Chapter Seven
Required JavaScript Variables ......................................................................................... 149
Widget Presentation and Administration.................................................................... 150
Widget Name............................................................................................................. 151
Administration Page Description................................................................................ 152

Index ................................................................................................................................ 153



1

Chapter One
Overview
Livelink UNITE is a customizable storage area that helps you organize and improve the
way you access Livelink data and information from a variety of other sources. It provides
its members with a single location from which they can access different types of
information and allows them to configure the appearance of that information to suit their
individual preferences. This document explains how to build custom information sources
with the Livelink UNITE Widget Development Kit.
This chapter provides an overview of Livelink UNITE and the knowledge required to
develop Livelink UNITE request-handler objects, called widgets.
Livelink UNITE Components, page 2
How Livelink UNITE Processes Requests, page 10
Prerequisite Knowledge, page 13
Widget Development Strategy, page 16
Livelink UNITE Components
2 Livelink UNITE Widget Developer's Guide

Livelink UNITE Components
Livelink UNITE is comprised of several types of distributed objects. The objects
communicate through the Common Object Request Broker Architecture (CORBA)
protocol.

Figure 1-1: Livelink UNITE System Architecture
Livelink UNITE Components
Overview 3

Widgets
Widgets are request-handler objects in Livelink UNITE; they are the interface to any
content provider presented through Livelink UNITE. Each Livelink UNITE section and
page is generated by a widget. For example, the Livelink Virtual Workspace widget
exposes Livelink items, and the Weather widget displays weather forecasts. Widgets
expose data by performing the following operations:
Contacting data sources
Retrieving data from the data source and caching it
Rendering data in Livelink UNITE
Providing a user interface for administration and configuration (if required)
Widgets are Java

objects that conform to Livelink UNITEs widget Interface Definition


Language

(IDL) specification. The widget interface specification contains descriptions of


the methods and data structures used to gather data from a content provider and render
it for display in a Livelink UNITE section or page. For more information about the
widget IDL specification, see Livelink UNITE IDL Interfaces, page 19.
Livelink UNITE Extension
The Livelink UNITE extension integrates with a Web server through Microsoft

Internet
Information Server ISAPI extension, or a Common Gateway Interface (CGI) program.
The Livelink UNITE extension manages the following events:
Member requests
Widget responses
Member access
Member Requests
Livelink UNITE requests are sent to Livelink UNITE in the form of a hypertext universal
resource locator (URL). The Li velink UNITE extension interprets and forwards the
requests to the appropriate request-handler object, or widgets. The Livelink UNITE
extension sends the following to widgets:
All information required to complete the request, including system settings
Member data, including system permissions, preferences, and cookies
The default browser language, which it determines by comparing the members list
of accept language settings with the accept languages in the Livelink UNITE registry
Optional arguments embedded in the URL
For more information about the data that the Livelink UNITE extension provides to
widgets, see the Livelink UNITE Customization Guide.
Livelink UNITE Components
4 Livelink UNITE Widget Developer's Guide

Widget Responses
Responses from Livelink UNITE widgets are returned to the Livelink UNITE extension.
Before returning results to the members browser, the extension performs the following
tasks:
Creates Livelink UNITE page headers and footers
Determines which browser accept language to use
Includes the data and JavaScript files specified by the widget
Member Access
The Livelink UNITE extension verifies that members are signed in to Livelink UNITE. If
the member is not signed in, the extension redirects the request to the Livelink UNITE
Sign In page.
Also, the Livelink UNITE extension retrieves and passes the members Livelink UNITE
profile as part of each request sent to a widget.
Front Page Widget
The Front Page widget generates the Livelink UNITE page that appears when Livelink
UNITE members sign in. The Livelink UNITE front page contains the tabs and sections
that a Livelink UNITE member creates and customizes. Each time a member signs in to
Livelink UNITE, a request is sent to the Front Page widget, which then processes that
request to produce the correct front page for the member.
When the Front Page widget receives a request, it performs the following operations:
Reads the Livelink UNITE members profile settings to determine which tabs and
sections to display on the front page.
Sends requests to the widgets that supply the information on the members front
page. For each section on the active tab, the Front Page widget contacts the
corresponding widget and retrieves the appropriate information.
The Front Page widget makes one-way calls to each widget; that is, it does not wait for a
widget to respond before it sends the next widget request. After it sends the requests to
the widgets, the Front Page widget waits for the widget to respond. If a widget does not
respond in a period specified by the front page timeout value, the widgets section
displays a timeout error in its corresponding section on the front page.
Livelink UNITE generates a new instance of the Front Page widget for each front page
request that it receives; however, Livelink UNITE deletes the instance as soon as the
Front Page widget completes the request and displays the corresponding members front
page.
Livelink UNITE Components
Overview 5

The following image is a sample front page, as generated by the default Front Page
widget. For information about adding tabs and sections to your front page, see the
Livelink UNITE User Online Help.

Figure 1-2: Sample Livelink UNITE Front Page
Profile Data
Livelink UNITE maintains site, system, and member profile data. The Site profile stores
information about the domains configured in a Livelink UNITE installation and global
administration settings for certain widgets. The System profile stores administrative
information for a Livelink UNITE domain. The member profile stores personalized
information for a Livelink UNITE member account.
The Livelink UNITE Profile Manager manages the Site, System, and Member profiles.
Although the Profile Manager is a required component of Livelink UNITE, it remains
completely transparent to Livelink UNITE members and administrators.
Livelink UNITE Components
6 Livelink UNITE Widget Developer's Guide

Site Profile
Each Livelink UNITE installation has a Site profile that stores the following information:
Domains, which includes information about the Livelink UNITE domains enabled in
the Livelink UNITE installation. The system maintains information in a default
domain named LivelinkUNITE_Site even if you do not enable domains in your
Livelink UNITE installation. For more information about domains, see Domains in
the Livelink UNITE Installation and Administration Guide.
Widgets , which includes widget administration settings that apply across all
domains in a Livelink UNITE installation
System Profile
Each Livelink UNITE domain has a System profile that stores administrative information
for the domain. By default, the System profile contains the following types of
information:
General, which includes general administrative properties for the Livelink UNITE
domain, such as sign-up capabilities and response timeout values. The System profile
stores the general administration settings that Livelink UNITE administrators specify
on the General Settings page in Livelink UNITE. For more information about general
settings, see Change General Settings in the Livelink UNITE Admin Online Help.
Views, which includes a list of all views defined in the Livelink UNITE domain and
their attributes. For more information about views, see Views in the Livelink UNITE
Installation and Administration Guide or the Livelink UNITE Views Online Help.
View Names, which is a list of all view names in the Livelink UNITE domain. Each
Livelink UNITE domain requires all views to have a unique name. When a new view
is created, the system checks the list of view names to ensure that a view with the
same view name does not already exist.
Passwords, which includes password properties for the Livelink UNITE domain,
such as the minimum length, the number of characters and digits required, the
password history size, and password expiration rules. For more information about
password settings, see Change Password Settings in the Livelink UNITE Admin
Online Help.
Livelink UNITE Components
Overview 7

Profiles, which includes default profile information that Livelink UNITE
administrators set for the Livelink UNITE domain. Each Livelink UNITE member
account includes a profile that contains his or her personal section and tab selections,
and custom settings. Livelink UNITE administrators can create default profiles and
make them available as templates for new Livelink UNITE member account profiles.
Also, if Livelink UNITE View Administrators want to make a particular members
profile configuration available to other Livelink UNITE members, they add that
profile to the list of profiles available on the Profiles menu for all members of the
view. Other members can select the profile and view its tabs and sections in read-
only mode. This allows View Administrators to publish pre-configured tabs and
sections to view members. For more information about default profiles and view
profiles, see the Livelink UNITE Admin Online Help and Livelink UNITE Views Online
Help.
Widgets , which includes administrative properties for each widget in the Livelink
UNITE domain, such as domain-specific administration information for custom
widgets.
Member Profile
The first time that a Livelink UNITE member signs in, Livelink UNITE generates a
member profile. All Livelink UNITE member accounts include a profile. Member profiles
store a members custom tab and section configuration settings. For example, if a
Livelink UNITE member adds a Weather section to a tab and configures the section to
display weather forecasts for certain cities, Livelink UNITE stores the section
configuration information in the members profile. Member profiles store all the
preferences and customizations that Livelink UNITE members can make, such as:
Member information (for example, a greeting, name, and company information)
Password
Default tab configuration
Members can view their member profiles by clicking My Profile on the Profiles menu.
System or View Administrators can prevent members from having access to member
profiles. If members cannot access member profiles, the tabs and sections they can view
are determined by the profiles published to the views to which they belong.
Livelink UNITE Components
8 Livelink UNITE Widget Developer's Guide

Naming Service Object
Livelink UNITEs Naming service object contains a directory of registered widgets, the
system profile, and other Livelink UNITE objects. A Livelink UNITE object must register
with the Naming service object before it can communicate with another Livelink UNITE
object. The Livelink UNITE extension locates the target object by referring to the listings
in Livelink UNITEs Naming service object. After the target object is found, subsequent
transactions continue between the objects, without calling the Naming service object.
Widgets refer to Livelink UNITEs Naming service object to:
Register the widget each time the widget starts
Unregister the widget each time the widget stops
A reference to Livelink UNITEs Naming service object is derived through a textual
Interoperable Object Reference (IOR) file. A textual IOR is an ASCII stream of
hexadecimal digits that represent a CORBA object reference. The location of the Livelink
UNITE Naming service object IOR file is:
UNITE_home\ior\naming.ior
where UNITE_home is the directory path to the folder where Livelink UNITE program
files are installed.
The Naming service object is accessed through operations specified in the JacORB IDL
file COSNaming.idl.
Livelink UNITE Components
Overview 9

System Log Object
Livelink UNITEs system log object allows widgets to write information to Livelink
UNITEs system log. Widgets access Livelink UNITEs system log object through
Livelink UNITEs System Log IDL specification. For more information about the System
Log IDL specification, see System Log Writer Interface, page 146.
How Livelink UNITE Processes Requests
10 Livelink UNITE Widget Developer's Guide

How Livelink UNITE Processes Requests
Members submit requests to Livelink UNITE through URLs. The Livelink UNITE
extension processes the sign-in and widget requests and returns the results to members.
Signing In
Livelink UNITEs default location is a request to display the front page for a guest
account. From the guest account, members can:
Sign in as an existing member and view the tabs and sections they configured in
previous sessions
Create a new member account on the Sign Up page if the administrator permits open
enrollment
Access the information sources (if any) configured by the system admi nistrator for
the guest account
The first time a member signs in, the Livelink UNITE extension creates a persistent
member profile to store the member's personal information. With each successive sign in,
the Livelink UNITE extension retrieves the member profile for reference for each request.
How Livelink UNITE Processes Requests
Overview 11

Widget Requests
The following diagram explains how Livelink UNITE processes a sample request for
processing from a widget (in this case, using ISAPI integration).

Figure 1-3: Sample Widget Request Processed by Livelink UNITE
How Livelink UNITE Processes Requests
12 Livelink UNITE Widget Developer's Guide

A member submits a request by clicking a link or image displayed in the browser.
For example, the member submits the following URL after clicking the Edit button
on the Weather section:
http://host/unite/unite.dll?widget=weather&Request=Config&Tab=T0002&Section=10001
The Web server forwards the request to the Livelink UNITE extension, which it
locates through the virtual directory mapping, unite.
The extension identifies the target widget weather. If no widget is specifi ed, the
system uses the Front Page widget by default.
The extension sends the request to the Weather widget. It also sends the information
required to complete the request, including the system and member profiles, and
passes any arguments from the URL, which in this example are:
Request=Config, Tab=T0002, Section=10001
where Config is the name of the request, T0002 is the tab where the section is
displayed, and 10001 is the placement of the section on the tab.
The widget receives the request and directs processing to its appropriate function. In
this example, the widgets RenderPage function reads the member profile to collect
the current configuration page settings and then generates JavaScript code that
makes up the Weather sections Configuration page. When processing finishes, the
widget passes the results to the Livelink UNITE extension.
The extension provides a page or section header and footer, inserts the JavaScript
and data generated by the widget as the body, and then returns it to the members
browser.
The members browser interprets the JavaScript functions and data to create the
Livelink UNITE page.
Prerequisite Knowledge
Overview 13

Prerequisite Knowledge
Livelink UNITE widget developers must have knowledge of the following:
Livelink UNITE member interface
Java
HTML and JavaScript
CORBA
Livelink UNITE Interface
Before beginning widget development, developers must understand the basic
functionality of the Livelink UNITE interface. For example, a developer should know:
Interface elements, like tabs, sections, and pages
Basic member tasks, like signing in to the system and personalizing the interface
Common administrative and configuration tasks for pre-packaged widgets
For more information about Livelink UNITEs interface, see the online help pages
provided throughout Livelink UNITE.
Java
Widget developers must have experience developing Java programs. Also, an IDL
compiler is required for both development platforms.
To develop Java widgets or to work with the Livelink UNITE Java sample widgets, Open
Text recommends that you use the Java Development Kit (JDK) version 1.4.
HTML and JavaScript
All information gathered by a widget is presented as HTML sent to a members browser.
The HTML produced by widgets is generated by Livelink UNITE JavaScript functions
that specify HTML code. Using JavaScript functions to specify section or page content is
a Livelink UNITE standard; it provides greater performance and more flexibility in
presenting information in a variety of languages. For more information about the
Livelink UNITE JavaScript functions, see Required JavaScript , page 149 in the Livelink
UNITE Customization Guide.
Prerequisite Knowledge
14 Livelink UNITE Widget Developer's Guide

CORBA
You must have Common Object Request Broker Architecture (CORBA) programming
knowledge before you can develop Livelink UNITE widgets. Livelink UNITE objects
communicate with each other through the CORBA protocol. CORBA is part of a suite of
standards developed and maintained by the Object Management Group (OMG). The
OMG is a consortium of software companies and academic institutions that are dedicated
to the development and promotion of standardized object software.
CORBA provides the basic infrastructure for distributed object systems that are multi-
platform and multi-language. CORBA applications can request services from each other
regardless of the language used to create them, the platform on which they operate, or
their location. A CORBA object behaves as if it were a local object even though it may
have been created with Java technology and may reside on a remote network server.
CORBA is a solution for organizations that need to extend the functionality of systems by
accessing services available in other applications. Rather than redesigning these systems
to suit the continually changing requirements of others, CORBA is implemented as a
distribution technique that allows diverse systems to interoperate. In a CORBA
environment, all applications that support CORBA can become objects that access one
another.
Interface Definition Language
Access to Livelink UNITE widgets and other objects is described by the OMG Interface
Definition Language (IDL). IDL is a programming language-neutral specification
language that loosely resembles C++. IDL describes object interfaces and primitive data
types used by CORBA objects. It serves as a contract between Livelink UNITE objects
that request services and widget objects that implement the requests.
Livelink UNITE IDL specification files are compiled in the development environment
where the widgets are developed. As a result, Livelink UNITE IDL operations are
mapped or translated into the constructs of the local programming language.
Prerequisite Knowledge
Overview 15

Object Request Broker
The foundation of any CORBA system like Livelink UNITE is the Object Request Broker
(ORB

). The ORB provides the basic communications capabilities that allow Livelink
UNITE objects to interact.
Livelink UNITE uses a proprietary ORB based on The Ace ORB (TAO).
CORBA Resources
For detailed information about CORBA, including lists of CORBA reference materials,
see the OMG web site at http://www.omg.org.
Widget Development Strategy
16 Livelink UNITE Widget Developer's Guide

Widget Development Strategy
There is no specific procedure that explains how to design a custom widget; however,
there are factors you may want to consider when you develop a widget. The following
are general steps that Open Text recommends you follow when developing a custom
widget.
Determine Widget Architecture
Design the widget architecture. A widget may consist of one or more objects. For
example, the News and Weather widgets consist of three widget objects; a main widget
renders section and page contents but it relies on feeder and cache widgets to gather and
store data.
Plan Widget Section and Page Features
Decide which features are available on the widgets section and pages. For example,
consider the following:
Does the widget require an Administration page?
Will the widget support a single or multiple Livelink UNITE domains?
What settings do users make on the widgets Configuration page?
Can members access detached or full-page views?
How much online help is necessary?
Livelink UNITE supports certain section and page features (for example, detached and
full-page views). For more information about widget features, see Widget Functions,
page 21.
Start Coding/Refer to the Sample Widget
The Livelink UNITE Widget Development Kit includes a Java sample bookmark widget.
You can install and run the sample widget in your Livelink UNITE system. The sample
widget program files contain detailed comments that explain how the sample methods
generate Livelink UNITE sections and pages.
In addition to providing reference information, you may choose to use the sample widget
program files as templates. For example, each sample contains all of the methods
required by the Livelink UNITE Widget IDL specification. Make copies of the sample
widget files and reuse the sample code that meets your needs. For more information
about the sample widgets, see Sample Widgets, page 35.
Your widgets RenderPage and RenderSection methods generate Livelink UNITE section
and page contents. The contents are specified through JavaScript variables and functions
specified in a widgets JavaScript files. You can create your own JavaScript functions, use
Widget Development Strategy
Overview 17

pre-defined Livelink UNITE JavaScript variables and functions, or use a combination of
custom and pre-defined variables and functions. For more information about Livelink
UNITEs JavaScript variables and functions and widget JavaScript files, see the Livelink
UNITE Customization Guide.
Set the Required Widget Property Variables
Livelink UNITE identifies a widget and its key characteristics through values you assign
to three required JavaScript variables in your widgets JavaScript files. For more
information about the required variables, see Required JavaScript Variables, page 149.
Test the Widget
Open Text recommends that you test your widget in a separate Livelink UNITE test
system before you add it to your Livelink UNITE production system. You must register
your widget with Livelink UNITE before you can make it available for testing.
The sample widgets contain a script that allows you to test your widget in debug mode
without installing it. You can adapt the sample widget scripts to meet your widgets
requirements. For more information about using the sample widget scripts to run your
widget in test mode, see Sample Widgets, page 35.
Install the Widget
After you test your widget to verify that it performs properly, install and register the
widget with the Livelink UNITE production system. The sample widgets contain an
installation script that automatically installs and registers a widget. You can adapt the
sample widget scripts to meet your widgets requirements. For more information about
using the sample widget scripts to install your widget, see Sample Widgets, page 35.
Widget Development Strategy
18 Livelink UNITE Widget Developer's Guide



19

Chapter Two
Livelink UNITE IDL Interfaces
Livelink UNITE makes available three Interface Definition Language (IDL) interfaces to
your custom widget. The interfaces define how a custom widget communicates with the
system. The Livelink UNITE IDL interfaces are:
Widgets , which are the request-handler objects in Livelink UNITE; they are the
interface to any content provider presented through Livelink UNITE
Profiles, which store information about the Livelink UNITE system and each
Livelink UNITE member
System log writer, which maintains Livelink UNITEs log file
This chapter provides a general overview of each interface. The following topics are
covered:
Widgets, page 20
Profiles, page 25
System Log Writer, page 29
Widgets
20 Livelink UNITE Widget Developer's Guide

Widgets
Widgets are Java programs that conform to Livelink UNITEs widget IDL specification.
The specification requires the widget to gather data from a content provider and render it
for display in a Livelink UNITE section or page, using specific methods and data
structures. How widgets gather data from content providers is beyond the scope of the
widget IDL specification. The IDL specification defines only how the data is rendered for
presentation through the Livelink UNITE interface.
Widget Architecture
A widgets functionality may be provided by a single widget object; however, some
widgets rely on more than one widget object to provide data to Livelink UNITE
members. For example, Livelink UNITEs News, Weather, and XML widgets rely on
feeder and cache widgets.
Feeder widgets locate and retrieve information from an external data source, such as a
Web site or data source file. Cache widgets store the data in a cache until the main widget
requires it.
Note Widgets must be thread safe because members can make simultaneous calls
to a widget.
Widget IDL File
Livelink UNITEs widget IDL file must be compiled in your development environment to
translate the IDL definitions into constructs of your development environment. Livelink
UNITEs widget IDL file is included in the Livelink UNITE Widget Development Kit in
the following location:
Livelink_UNITE_WDK\idl\MLLWidget.idl
where Livelink_UNITE_WDK is the path and directory where you installed the Livelink
UNITE Widget Development Kit.
Registering Widgets
Widget objects are single, transient objects registered with Livelink UNITEs Naming
service object. The Naming service object contains a directory listing of all registered
widgets. Livelink UNITE uses the listing in the Naming service object to locate a widget
the first time a request for the widget is processed. Successive transactions continue
directly between objects, without referring to Livelink UNITEs Naming service object.
Widgets
Livelink UNITE IDL Interfaces 21

Widget Functions
A widget can provide any functionality its developer can create. However, the widget
IDL specification requires that each widget include several operations that provide a
variety of functions. The most important required functions perform:
Section rendering
Page rendering
Section Rendering
A widgets section-rendering function generates the content displayed in a Livelink
UNITE section. A section often contains links or buttons that provide access to a widgets
page-rendering functions, such as the Configuration page and full-page views of the
section. The widget IDL specification includes the RenderSection operation to process
section requests. For more information about the RenderSection operation, see
RenderSection, page 73.
Widgets
22 Livelink UNITE Widget Developer's Guide

Page Rendering
A widgets page-rendering function generates the content displayed in a Livelink UNITE
page. Some commonly implemented page functions that Livelink UNITE supports
include:
Full-page views
Detach-page view
Configuration page
Administration page
Livelink UNITEs widget IDL specification defines a RenderPage operation that
processes all page function requests. For more information about the RenderPage
operation, see RenderPage, page 74.
Full-Page View
A full-page view function displays a widgets content, including Livelink UNITE headers
and footers in a members browser window. Optionally, the page can contain banner
advertisements. For example, Livelink UNITEs front page is a full-page view created by
the Front Page widget.
Detach-Page View
A detach page view function displays a section in a separate browser window of a
specified size. The window includes basic Livelink UNITE headers and footers and a
Cancel button used to close the window.
If a section is detachable, the system displays the detach icon on the section toolbar.
Also, the system assigns a detach request URL to the icon by passing a Livelink UNITE
JavaScript function call that includes the section identifier as a parameter. The settings for
the detach section function are specified in a data structure returned by the
RenderSection operation. For more information about configuring the detach function,
see the bDetach field description in Table 6-2, page 86.
Configuration Page
A configuration function generates the Configuration page. A widgets Configuration
page allows a member to customize a widgets output. For example, a widget may allow
members to override the default section title. The widgets Configuration page, accessible
from the Edit button on the section toolbar, provides a text box where the member
supplies a new title. Typically, a separate, complementary configuration function gathers
data from the page and performs any changes a member submits.
Widgets
Livelink UNITE IDL Interfaces 23

If the widget indicates to Livelink UNITE that it is configurable, the system assigns a
configuration request URL to the Edit button by passing a Livelink UNITE JavaScript
function call that includes the sections tab and placement information.
The settings for the configuration function are specified in a data structure returned by
the RenderSection operation. For more information about configuring the configuration
function, see the bConfig field description in Table 6-2, page 86.
Administration Page
A widgets Administration page allows only members with administrator privileges to
configure a widgets global options. For example, the Weather Feeder widget
periodically gathers weather data for member-selected sites. The Weather Feeder widget
Administration page contains a refresh setting that indicates how often the widget checks
for new weather data. A widgets administration page is accessible from a link on
Livelink UNITEs Section Administration page if it supports a domain or from the Global
Section Administration page if the widget supports the global domain.
Widget Online Help
You can create online help pages (for example, configuration and administration help
pages) as required for your widget. By default, Livelink UNITE looks for your custom
widgets help files in the following location:
UNITE_home\support\help\language\widget
where UNITE_home is the directory path to the folder where Livelink UNITE program
files are installed, language is the browser accept language, and widget is the widget name.
For example, the English version of the default Help file for the News widget is:
UNITE_home\support\help\en\News\default.html
Livelink UNITE provides two ways to access widget online help pages:
The For This Page command on the Help menu of each widget page. By default, the
system checks your widgets help directory for an HTML file that matches the
current action name (for example, for the Administration page created by the action
Admin, Livelink UNITE looks for Admin.html). If no HTML page exists that matches
the action name, Livelink UNITE locates the file default.html. If that file does not
exist, members receive a File Not Found error in the help window.
The About Livelink UNITE page, accessible from the About Livelink UNITE
command on the Help menu, includes a link to a general description of your widget
that must be stored in a file named About.html.
Widgets
24 Livelink UNITE Widget Developer's Guide

Custom Help File Location
You can specify an alternate location for your custom widgets online help files by
specifying the help file name and location in the wsHelpURL field of the PageInfo data
structure. For more information about the wsHelpURL field, see PageInfo," page 93.
Profiles
Livelink UNITE IDL Interfaces 25

Profiles
Livelink UNITE profiles are persistent objects that store member and system information.
The system features two kinds of profiles:
Member profile
System profile
Widget developers use the operations defined in the Livelink UNITE profile IDL
specification to retrieve, add, and modify information in the profiles.
Profile Structure
A Livelink UNITE profile supports a tree structure of nodes. Each node in the tree
contains at least a default property and, optionally, other properties. A property consists
of a name and value. Property values are always String values. Also, values can be one-
way encrypted for security purposes. The default value for a property is a blank string
().
Important Root node properties are reserved for use by Livelink UNITE. Do not create
properties in the root node.

Figure 2-1: Livelink UNITE Profile Structure
Profiles
26 Livelink UNITE Widget Developer's Guide

Node Key Path
Profile nodes and their properties are referenced through node key paths. Node key
paths consist of node names separated by slashes leading to a nodes position in the
registry tree. Leading and/or trailing slashes are ignored. Node and property names are
case sensitive. For example, the node key path for a widget named MyWidget in the
system profile is:
/Widgets/MyWidget
Member Profiles
When a member signs up or an Administrator creates a new member account, Livelink
UNITE creates a member profile to store any configurations or preferences a member
specifies. The member profile maintains the member password and personal information
provided at sign up, and the names and locations of all tabs and sections. Also, the
member profile contains any member configurable widget properties. For example, each
member specifies the kind of news to display in the News widget and which cities to
monitor in the Weather widget.
Each time a member signs in to Livelink UNITE, the system retrieves the member profile
and makes it available as part of any request sent to a widget. The widget uses operations
defined in the profile IDL specification to retrieve or update the member profile.
Note Do not store large amounts of data in member profiles. Open Text
recommends that widgets store large amounts of data in a relational
database system or some other repository.
Member Profile Structure
By default, the member profile contains a Tabs root node. The Tabs node contains:
A default property that identifies which tab is displayed by default on the members
Livelink UNITE front page.
A node for each member tab. In turn, each tab node contains a node for each section
on the tab. The section nodes contain the configurable properties (and possibly, more
nodes) for the widget displayed in that section.
Tabs and section nodes are supplied in each request made to a widget. For more
information about tab and section values passed to a widget, see SectionSpec, page 88
and PageSpec, page 101.
Profiles
Livelink UNITE IDL Interfaces 27

Retrieving Member Profile Objects
The Livelink UNITE extension supplies with each request a reference to the member
profile of the requestor. For more information about the member profile passed to a
widget, see the oProfile field of SectionSpec, page 88 and PageSpec, page 101.
System Profile
Each Livelink UNITE system contains a single Livelink UNITE system profile that
contains administrative information for the Livelink UNITE installation. You can add
administrative properties for your widget to the existing nodes, or you can create custom
nodes in the system profile. By default, the Livelink UNITE system profile contains eight
nodes.
Table 2-1: System Profile Object Default Nodes
Node Contains
AllGroups Default group settings and Livelink UNITE view configurations
General General administrative properties for the Livelink UNITE site, such as
sign-up capabilities and response timeout values. The System profile
stores the general administration settings that Livelink UNITE
administrators specify on the General Settings page in Livelink UNITE
GroupNames All view names configured in the Livelink UNITE installation
Groups View information for the Livelink UNITE site; for internal use only
Passwords Password properties for the Livelink UNITE site, such as the minimum
length, the required number of characters and digits, the password
history size, and password expiration rules
ProfileDisplay
Names
Display names of all published profiles in the system
Profiles Default profile and category information that Livelink UNITE
administrators set for the Livelink UNITE site. Each Livelink UNITE
member has a profile that contains their personal section and tab
selections, and custom settings. Livelink UNITE administrators make
certain profiles available to new Livelink UNITE members by creating
default profiles. If Livelink UNITE administrators want to make a
particular tab configuration available to other Livelink UNITE members
(and not the entire profile, which contains the tab configuration), they
create categories.
Widgets Administrative properties for each widget at the Livelink UNITE site.
Here, widget developers add administration information for the custom
widgets that they create.
Profiles
28 Livelink UNITE Widget Developer's Guide

You can add properties to the existing nodes or create your own nodes. However, Open
Text strongly recommends that you create a node for your widget in the system objects
Widget node to store any widget administrative properties.
Retrieving the System Profile
The Livelink UNITE extension supplies with each request a reference to the system
profile. For more information about the system profile passed to a widget, see the
oSystemProfile field in Table 6-3, page 88, and Table 6-9, page 101.
Profile IDL File
The Livelink UNITE profile IDL file must be compiled in your development
environment. This translates the Livelink UNITE profile IDL operations into constructs of
the local programming language. Livelink UNITEs profile IDL file is extracted from the
Livelink UNITE Widget Development Kit file in the following location:
Livelink_UNITE_WDK\idl\MLLProfile.idl
where Livelink_UNITE_WDK is the directory where you extracted the Livelink UNITE
Development Kit files.
Viewing Profile Contents
The Livelink UNITE system provides a backup utility that extracts the content of the
profile manager database in extensible markup language (XML) file format. Profiles and
their properties are grouped together and labeled with XML markup tags. For more
information about the Livelink UNITE backup utility, see the Livelink UNITE Installation
and Administration Guide.
System Log Writer
Livelink UNITE IDL Interfaces 29

System Log Writer
Livelink UNITE logs different types of information as various operations are performed
in the system. The different types of information include:
Low-level information
System information, including client requests, page response times, and section
response times
Time and usage counts for all active widgets
Logging System Information
The Livelink UNITE System Log Writer logs Livelink UNITEs system status
information. The System Log Writer records information in a log file named
myLivelink.log, which is stored in Livelink UNITEs log directory. Each time a new log
file is created, existing log files are renamed myLivelink_n.log, where n is a number that
is incremented by one.
The System Log Writer automatically records certain Livelink UNITE system information
(for example, Livelink server states). If you want to record additional Livelink UNITE
system information in the Livelink UNITE log file, you specify log settings in the
Microsoft

Windows

registry or the UNITE_home/wwwbin/myLivelink file on Sun Solaris.


For more information about how to specify log settings, see the Livelink UNITE
Installation and Administration Guide.
Log Settings
Log settings indicate what information a widget writes to a log file.
Table 2-2: Livelink UNITE Log Settings
Value Use
C Logs each request that a widget receives. This means that each time a Livelink
UNITE member clicks a link to perform an operation, Livelink UNITE records
the corresponding operation in the Livelink UNITE log file.
P Logs page response times. This value indicates how long it took Livelink
UNITE to build or draw a page of information.
S Logs section response times. This value indicates how long it took a particular
Livelink UNITE section to respond when Livelink UNITE prompted it to
update.
For more information about the system log writer settings passed to a widget, see the
wsLogSettings field in Table 6-3, page 88 and Table 6-9, page 101.
System Log Writer
30 Livelink UNITE Widget Developer's Guide

Access to the System Log Writer Object
The Livelink UNITE extension supplies with each request a reference to the system log
writer object. For more information about the system log writer object reference passed to
a widget, see the oLogWriter field in Table 6-3, page 88 and Table 6-9, page 101.


31

Chapter Three
Installing the Widget Developers Kit
Before you can develop a custom widget, you must install the Livelink UNITE Widget
Development Kit (WDK). The Livelink UNITE WDK includes Livelink UNITE Interface
Definition Language (IDL) files, and sample widget files that will assist you in building
your own widget. The following sections are covered:
Installing the Livelink UNITE WDK on Windows Computers, page 32
Installing the Livelink UNITE WDK on Solaris Computers, page 33

Installing the Livelink UNITE WDK on Windows Computers
32 Livelink UNITE Widget Developer's Guide

Installing the Livelink UNITE WDK on Windows
Computers
The Livelink UNITE WDK is distributed as a self-extracting archive on the Open Text
Knowledge Center:
https://knowledge.opentext.com/knowledge/llisapi.dll?func=ll&objId=2821423&objAction=browse&sort=name
You must download the Livelink UNITE WDK file from the Open Text Knowledge
Center before you can install the Livelink UNITE WDK. Verify that the computers on
which you perform the Livelink UNITE WDK installation fulfill the minimum system
requirements. For more information about system requirements, see Java Sample
Widget Requirements," page 36.
To install the Livelink UNITE WDK on Windows computers:
1. Download the Livelink UNITE WDK self-extracting archive to your computer.
2. Execute Livelink UNITE WDK self-extracting archive
Livelink_UNITE_WDK_910_NT.exe.
3. When prompted, choose the directory where the Livelink UNITE WDK files are to
be extracted.
The Livelink UNITE WDK files are extracted to the directory you specify.

Installing the Livelink UNITE WDK on Solaris Computers
Installing the Widget Developers Kit 33

Installing the Livelink UNITE WDK on Solaris
Computers
The Livelink UNITE WDK installation program is distributed in a UNIX tar program on
the Open Text Knowledge Center:
https://knowledge.opentext.com/knowledge/llisapi.dll?func=ll&objId=2821423&objAction=browse&sort=name
You must download the Livelink UNITE WDK tar file from the Open Text Knowledge
Center before you can install the Livelink UNITE WDK. Verify that the computers on
which you perform the Livelink UNITE WDK installation fulfill the minimum system
requirements. For more information about system requirements, see Java Sample
Widget Requirements," page 36.
To install the Livelink UNITE WDK on Solaris computers:
1. Download the Livelink UNITE WDK tar file to your computer.
2. Extract the Livelink UNITE WDK installation program file from the tar file by
entering the following command:
tar xvf Livelink_UNITE_WDK_910_Sun.tar
3. Create a directory where you want the Livelink UNITE WDK files to be installed.
4. Move to the directory where you extracted the installation program, and then
execute the Livelink UNITE WDK installation program by entering the following
command:
./Livelink_UNITE_WDK_910_Sun
5. When prompted, specify the directory where the Livelink UNITE WDK files are to
be installed. The default location is the directory from which you execute the
installation program.
6. Press Enter to confirm the installation directory, or specify another installation
directory.
The Livelink UNITE WDK files are installed in the directory you specify.

Installing the Livelink UNITE WDK on Solaris Computers
34 Livelink UNITE Widget Developer's Guide


35

Chapter Four
Sample Widgets
To help you understand how widgets operate, the Livelink UNITE Widget Development
Kit includes sample widgets. The information in this chapter, combined with detailed
comments in the widget program files, describes the sample widgets.
Overview, page 36
Java Sample, page 37
Using the Sample Widget, page 44
Solaris Users Commands and descriptions in this chapter include directory paths that
may contain backward slash characters. You must replace the backward
slash characters with forward slash characters to make them applicable
on Solaris computers.

Overview
36 Livelink UNITE Widget Developer's Guide

Overview
The Livelink UNITE Widget Developers Kit includes a sample bookmark widget. The
widget generates a Livelink UNITE section that acts as a repository for Web site
addresses called bookmarks. Livelink UNITE members use a bookmark section to record
their favorite Web sites.
The sample widget helps you better understand widgets by providing the following:
Utility scripts that automate how to build and install the widget using Livelink
UNITE IDL files
Detailed comments in program files. The comments explain how the widget
generates data for the sections and pages it makes available to Livelink UNITE.
A fully functional Livelink UNITE component. You can use the sample widget to
practice testing, installing, and removing components from your system.
Sample Widget Files
In addition to widget code, the sample includes everything you need to build and start a
sample widget. The samples include the following types of files:
Widget program and header files
IDL files
JavaScript and online help files
Build and execution scripts
Java Sample Widget Requirements
The Java sample widget, JBookmark, requires the following software installed on the
machine where it is built and run:
Livelink UNITE 9.1
Windows NT

4.0 (with Service Pack 5 or later), Windows 2000, or Sun Solaris 2.7 or
later
Sun Java Development Kit (JDK) 1.4
JacORB 1.3.30
Microsoft Visual C++ 6.0 (with Service Pack 3) is required on Windows or Sun
WorkShop Compiler C++ 5.0 on Solaris if you want to build or debug the
JService.exe or JLoader application.
Overview
Sample Widgets 37

Java Sample
This section explains how to build and install the JBookmark sample widget.
Java Sample Widget Files
The following table describes the files that comprise the JBookmark sample widget.
Table 4-1: JBookmark Files
Folder Files Use
Idl LLSysLogWriter.idl
MLLProfile.idl
MLLWidget.idl
MLLCallBack.idl
The Livelink UNITE Interface
Definition Language (IDL) files
Java WidgetImpl.java
WidgetLog.java
WidgetMain.java
WidgetUtils.java
WidgetLogWindow.java
WidgetLogFile.java
The Java program common files
Java\bin Debugwidget
installwidget
makewidget
makeidl
uninstallwidget

myllConfigSuper.exe
(Windows)


readme.txt (Windows)
README (Solaris)
Scripts used to build and install
the sample widget




An internal program file that
installs and uninstalls the sample
widget Windows service

Instructions and tips on how to
build and install the JBookmark
widget
Java\bin\java2 Environment


JService.exe
(Windows)
JLoader
(Solaris)
Script that defines site settings
(for use by Java 2 users)

The executable file that runs the
Java Virtual Machine (JVM) used
by the widget (for use by Java 2
users)
Overview
38 Livelink UNITE Widget Developer's Guide

Table 4-1: JBookmark Files
Folder Files Use
Java\bin\src\JService
(Windows only)
JService.cpp
JService.dsp_jdk1.1.8
JService.dsp_jdk1.2.2
JService.dsp_jdk1.3.0
JService.dsw
JService.h
JService program files
java\bin\src\JLoader
(Solairs only)
JLoader.C
makeJLoader
JLoader program files
java\JBookmark JBookmark.java



MLLWidget_JBookmark.js
MLLWidget_JBookmark_en.js
The widget Java file that contains
the Livelink UNITE section and
page functions

JBookmark JavaScript files
support WidgetUtil.js JBookmark widget JavaScript
utilities
java\JBookmark\
help\en\JBookmark
About.html
AddBookmark.html
Admin.html
Config.html
DeleteBookmark.html
Detach.html
FullPage.html
ModifyBookmark.html
SortBookmark.html
JBookmark online help files

Overview
Sample Widgets 39

Build the JBookmark Widget
To build the JBookmark widget, you must complete the following tasks:
Set the widget environment
Compile the IDL and Java files
Copy the JBookmark support files
Note For more information about building the JBookmark sample widget, see the
sample widget java\bin\readme.txt (Windows) or java/bin/README
(Solaris) file.
Set the Widget Environment
JBookmark scripts call the environment file to set environment variables. You specify
information about your computer, Livelink UNITE, and other software programs to the
variable declarations in the environment file.
To configure the environment file:
1. Copy the environment.bat and JService.exe (Windows) or the environment script
and JLoader (Solaris) files into the Livelink_UNITE_WDK\java\bin directory from
the Livelink_UNITE_WDK\java\bin\java2 directory where Livelink_UNITE_WDK is
the directory where you installed the Livelink UNITE Widget Development Kit.
2. Edit the environment file and follow the instructions to specify your site settings.
Compile the IDL
After setting the environment variables, you compile the IDL files into Java files and then
compile the Java files into Java classes with the makeidl script. The Java files and classes
are placed in the Livelink_UNITE_WDK\idl\lib directory.
To compile JBookmark IDL files:
1. At a command prompt, move to the Livelink_UNITE_WDK\java\bin directory.
2. Enter the following command:
makeidl
Overview
40 Livelink UNITE Widget Developer's Guide

Compile the JBookmark Java Files
The makewidget script compiles the JBookmark Java files. The resulting class files are
placed in the \lib folder in the directory where the Java files reside.
To compile the JBookmark Java files:
1. At a command prompt, move to the Livelink_UNITE_WDK\java\bin directory.
2. The makewidget script requires a widget name parameter. For the JBookmark
widget, the widget name parameter is JBookmark. Enter the following command:
makewidget JBookmark
Copy JBookmark Support Files
The final step in building the JBookmark widget is copying its JavaScript and online help
files into the Livelink UNITE support directory (for example, d:\UNITE_home\support).
Copy the following files to the Livelink UNITE support directory:
The MLLWidget_JBookmark.js and MLLWidget_JBookmark_en.js found in the
Livelink_UNITE_WDK\java\JBookmark directory.
The online help files stored in the
Livelink_UNITE_WDK\java\JBookmark\help\en\JBookmark directory. Copy the
help folder to the UNITE_home\support directory to add the JBookmark files to the
Livelink UNITE help system.
The WidgetUtil.js file found in the Livelink_UNITE_WDK\support directory.
Overview
Sample Widgets 41

Test and Install the JBookmark Widget
After the JBookmark widget files have been compiled, you are ready to test and install
the widget.
Note Start Livelink UNITE (including the Naming service) before you attempt to
start the JBookmark widget.
Test JBookmark
The debugwidget script runs JBookmark as a Java console application. Run JBookmark
using the debug script to verify that the build process completed properly.
To test the JBookmark application:
1. At a command prompt, move to the Livelink_UNITE_WDK\java\bin directory.
2. The debugwidget script requires a widget name parameter. For the JBookmark
widget, the widget name parameter is JBookmark. Enter the following command:
debugwidget JBookmark
JBookmark starts as a console application.

Figure 4-1: JBookmark Java Console


Overview
42 Livelink UNITE Widget Developer's Guide


3. Test the sample widget in debug mode before you install JBookmark. You test the
sample widget by accessing a JBookmark section in Livelink UNITE to verify that it
is working properly. For more information about accessing the sample widget
section, see Using the Sample Widget, page 44.
4. To stop JBookmark, at the command prompt where you started the debugwidget
script, press CTRL+C.
Install JBookmark
The installwidget script adds the JBookmark widget to the Livelink UNITE SuperService
on Windows computers or includes it in the UNITE_home/widgets file on Solaris
computers.
To install and start the JBookmark widget:
1. At a command prompt, move to the Livelink_UNITE_WDK\java\bin directory.
2. The installwidget script requires a widget name parameter. For the JBookmark
widget, the widget name parameter is JBookmark. Enter the following command:
installwidget JBookmark
3. Start the JBookmark widget by starting the MLLWidget_JBookmark servi ce on
Windows computers or by using the startwidget script on Solaris computers.
Troubleshooting
If you receive an error when starting the JBookmark widget, ensure that the correct
version of the JVM appears in your path before any other version of the JVM. If you
update your PATH variable on Windows computers, you must reboot your system
before the change takes effect.
Stop the JBookmark Widget
You can stop the JBookmark widget by stopping the MLLWidget_JBookmark service on
Windows computers or by executing the Livelink UNITE stopwidget script on Solaris
computers.
Overview
Sample Widgets 43

Uninstall the JBookmark Widget
The uninstallwidget script removes the JBookmark widget from the Livelink UNITE
SuperService on Windows computers or the UNITE_home/widgets file on Solaris.
To uninstall the JBookmark widget:
1. Disable the JBookmark widget in the views for which it was enabled.
2. Stop the JBookmark widget.
3. At a command prompt, move to the Livelink_UNITE_WDK\java\bin directory.
4. The uninstallwidget script requires a widget name parameter. For the JBookmark
widget, the widget name parameter is JBookmark. Enter the following command:
uninstallwidget JBookmark
The widget is removed.
5. Manually remove the UNITE_home/MLLWidget_JBookmark.js and
MLLWidget_JBookmark_en.js files, and the online help files stored in the
UNITE_home/support/help/en/JBookmark folder.

Using the Sample Widget
44 Livelink UNITE Widget Developer's Guide

Using the Sample Widget
This section explains how to administer and use the Sample Bookmark widget.
Administration
After you have built and started the JBookmark widget in Livelink UNITE, you can make
the Sample Bookmark section available for use in Livelink UNITE.
To make the sample widget available:
1. Log in to Livelink UNITE as Admin.
2. Click View on the Administration menu.
3. Click the name of a view in which you want to enable the Sample Bookmark section.
4. Click Section Availability in the Functions list.
5. Click the Enabled radio button.
6. Click the Submit button, and then click the Finished button.
7. On the Administration menu, choose System, and then click Section
Administration.
8. Click the Administer link next to Sample Bookmark to administer the section.
9. On the Section Administration page, type the message to be displayed in a Sample
Bookmark section above a members bookmarks.
10. Click the Submit button, and then the Finished button.

Figure 4-2: Sample Administration Page
Using the Sample Widget
Sample Widgets 45

Adding a Section
You must add a Sample Bookmark Widget section to a tab.
To add a section:
1. Click the Edit button on the tab where you want to access the Sample Bookmark
Widget section.
2. Add the Sample Bookmark Widget section to the tab column.
3. Click the Submit button.
The tab displays the Sample Bookmark Widget section.

Figure 4-3: Sample Tab with Sample Bookmark Widget (Java) Section
Using the Sample Widget
46 Livelink UNITE Widget Developer's Guide

Configuration
After you add a Sample Bookmark Widget section to a tab, you add bookmarks to it on
the Configuration page.
To add a bookmark:
1. Click the Edit button on the section title bar.
2. Click New Bookmark.
3. In the Name field, type the bookmark name used as the link text.
4. In the URL field, type the URL.
5. In the Description field, type a bookmark description. The description is displayed
only in sections that appear in a wide tab column, and detached and full-page
views.
6. Repeat steps 2 through 5 to create another bookmark.
7. Click the Submit button to save your bookmarks and return to the front page.

Figure 4-4: Sample Configuration Page

Using the Sample Widget
Sample Widgets 47

Sample Widget Features
A Sample Bookmark Widget section contains the following widget functionality:
Configuration page generated by clicking the Edit button where users specify the
bookmarks the want to save
Full-page view created by clicking the Sample Bookmark Widget link in the section
title bar
Detached view accessed by clicking the Detach button

Figure 4-5: Sample Bookmark Widget Section

Using the Sample Widget
48 Livelink UNITE Widget Developer's Guide

Section Statistics
The JBookmark widget maintains performance statistics and displays them on the
Livelink UNITE Administration Section Status page.

Figure 4-6: Sample Bookmark Widget Statistics From the Section Status page



49

Chapter Five
Upgrading Custom Widgets
Previous releases of Livelink UNITE were distributed under the product name
myLivelink. If you created a custom widget using the myLivelink Widget Development
Kit (WDK), you must upgrade your custom widget before it can function in a Livelink
UNITE system. The following topics are covered:
Overview, page 50
Upgrading Java Custom Widget Code, page 52
JavaScript and Online Help Upgrades, page 61

Overview
50 Livelink UNITE Widget Developer's Guide

Overview
You must upgrade the custom widgets you created in myLivelink before they will run in
Livelink UNITE. The upgrade path you follow depends on the myLivelink release from
which you wish to upgrade.
If your custom widget is running in a myLivelink 9.0 system, see Upgrading Custom
Widgets from myLivelink 9.0 to Livelink UNITE, page 51.
If your custom widget is running in a myLivelink release prior to myLivelink 9.0, you
must upgrade it to the myLivelink 9.0 convention before upgrading it for use in Livelink
UNITE. For more information about upgrading a custom widget from a prior myLivelink
release to the myLivelink 9.0 convention, see Upgrading Custom Widgets from a
myLivelink Release Pre-9.0, page 52.
Upgrading C++ Custom Widgets
Livelink UNITE supports custom widgets written in Java only. If you created a custom
widget in C++ for a myLivelink release, you must port your C++ code to Java before you
can upgrade it to run in Livelink UNITE 9.1.
Upgrading Custom Widgets from myLivelink 9.0 to Livelink UNITE
Upgrading Custom Widgets 51

Upgrading Custom Widgets from myLivelink 9.0 to
Livelink UNITE
You must modify custom widgets that run on myLivelink 9.0 before they will operate in
Livelink UNITE.
Convert the Livelink UNITE IDL Files
Livelink UNITE 9.1 uses updated Interface Definition Language (IDL) files that you must
convert to Java (for example, using the WDKs makeidl script) for use with your custom
widget code. For more information about the makeidl script, see Compile the IDL,
page 39.
Recompile Custom Widgets
After you convert the Livelink UNITE IDL files to Java code, you must recompile your
custom widget to use the new code.
ORB Modifications
Livelink UNITE uses the JacORB, a different ORB than the one included in all myLivelink
releases. If your custom widget uses an ORB other than the JacORB, you may have to
modify your widget code to make it compatible with the JacORB included in Livelink
UNITE. For more information about how to make a custom ORB interoperable with the
JacORB, see your ORB documentation.
Note If your custom widget is based on the sample widget code delivered with
myLivelink 9.0 or earlier and you have not altered function calls to the ORB,
you can upgrade your custom widget without changing calls to the ORB by
following the upgrade procedures in this chapter.

Upgrading Custom Widgets from a myLivelink Release Pre-9.0
52 Livelink UNITE Widget Developer's Guide

Upgrading Custom Widgets from a myLivelink
Release Pre-9.0
The myLivelink 9.0 release includes a number of features and enhanced functionality not
available in previous myLivelink releases. These enhancements required changes to the
myLivelink software architecture. Custom widgets developed in previous myLivelink
releases must be updated to support myLivelink 9.0 standards before they can be
upgraded to run in Livelink UNITE.
To upgrade a custom widget to run in myLivelink 9.0, you must complete the following:
Upgrade your custom widget code as instructed in Upgrading Java Custom Widget
Code, page 52.
Modify your custom widgets JavaScript support files and online help as described in
JavaScript and Online Help Upgrades, page 61.
Upgrading Java Custom Widget Code
This section explains how to modify a myLivelink 1.0 custom widget so that it runs in
myLivelink 9.0. Before you can upgrade your custom widget, you must download and
install the myLivelink 9.0 WDK from the Open Text Knowledge Center.
Important The upgrade instructions in this section apply only to those custom widgets
developed using the batch files and Java infrastructure delivered with the
myLivelink 1.0 Widget Development Kit to build and run your custom
widget.
Using the JBookmark Sample Widget
You must refer to the JBookmark sample widget included in the myLivelink 9.0 WDK as
a guide to help you upgrade your widget. New and upgraded Java and JavaScript code
in the JBookmark sample widget program and JavaScript files is explained in code
comments. To find modifications made to meet myLivelink 9.0 conventions and
corresponding comments, search the files for comments and lines containing 9.0.
Open Text recommends that you configure and install the JBookmark 9.0 sample widget
in your myLivelink 9.0 system before you upgrade a myLivelink 1.0 widget. If you do not
configure and install the JBookmark sample widget, you must do the following before
you upgrade any widget:
Update the variable assignments in the myLivelink_WDK9.0\java\bin\environment
file, where myLivelink_9.0WDK is the directory where the myLivelink 9.0 WDK is
installed.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 53

Compile the myLivelink 9.0 Interface Definition Language (IDL) files by executing
the myLivelink_WDK9.0\java\bin\makeidl script.
Optionally, you may consider upgrading the JBookmark 1.0 widget before you start
modifying your own widget. By upgrading the JBookmark 1.0 widget code to
myLivelink 9.0 conventions, you can see the types of modifications required to bring
your custom widget to myLivelink 9.0 conventions. To upgrade the JBookmark 1.0
widget, install the myLivelink 1.0 and 9.0 WDKs and follow the instructions in this
chapter.
Code and JavaScript Upgrades
You must modify your custom widget code to make it compatible with CORBA, IDL, and
support function improvements in Livelink UNITE 9.0. If you attempt to compile your
existing widget code (using the Livelink UNITE 9.0 WDK makewidget utility) without
making any changes, you may receive errors. To make the required modifications to your
custom widget, complete the tasks described in this section.
Copy Your Widget Code
Before you begin to upgrade your custom widget, copy the directory that contains the
custom widget code to the myLivelink_WDK\java directory, where myLivelink_WDK is
the myLivelink 9.0 WDK installation directory. The custom widget directory must be at
the same level as the JBookmark directory.
Profile Operation Data Structure
Two new fields, wsParam4 and wsParam5, were added to the ProfileOperation
data structure. You must add two empty string parameters to each instance of the
ProfileOperations data structure in your code. For example, an instance in the
JBookmark 1.0 widget code is:
profOperations[ 0 ] = new ProfileOperation(OperationType.kPropertySet.value(),
keyPath, gsSectionTitleProperty, sectionTitle);
The JBookmark 9.0 widget code is:
profOperations[ 0 ] = new ProfileOperation(OperationType.kPropertySet.value(),
keyPath, gsSectionTitleProperty, sectionTitle, "", "" );
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
54 Livelink UNITE Widget Developer's Guide

System Profile Access
A new feature in myLivelink 9.0 is that you can access the System Profile through a field
in the SectionSpec and the PageSpec data structures. You must update all calls in
your code to the WidgetMain.SystemProfile() method that provided access to the
myLivelink 1.0 System Profile. To read information from the System Profile, update your
code to use the spec.oSystemProfile.PropertyGet() profile operation, where spec
is a SectionSpec or PageSpec data structure. If your code needs to write information
to the System Profile, use the spec.oSystemProfile.Modify() profile operation.
You may need to redesign the method your custom widget code uses to gain access to
the System Profile in a myLivelink 1.0 system. For example, in the JBookmark 1.0 sample
widget, the Administration message displayed at the top of each JBookmark section and
page was retrieved from the System Profile in the Notify() method. However, a
PageSpec or SectionSpec data structure is not passed into the Notify() method; so
there is no way to access the profile operations. The RenderSection and RenderPage
functions in the JBookmark 9.0 widget were redesigned to retrieve the Administration
message from the System Profile, using the operations available through the PageSpec
and SectionSpec data structures. Refer to the Notify() method and all instances of
the GetAdminMessage() method in the JBookmark 9.0 code for an example of how to
upgrade your widget to access the System Profile.
Upgrade Status Methods
myLivelink 9.0 includes status methods, SectionsRenderedStats and
PagesRenderedStats, that provide enhanced status reporting and synchronization.
These methods replace the existing methods that set and retrieve page and section counts
displayed on the myLivelink Section Status page. The myLivelink 1.0 methods that have
been replaced in myLivelink 9.0 are:
IncrementSectionsRendered
ClearSectionsRendered
GetSectionsRendered
IncrementPagesRendered
ClearPagesRendered
GetPagesRendered
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 55

Update your custom widget code to include the new status methods by copying the new
method declarations from the JBookmark program file. You can locate the code you must
copy to your custom widget code by searching for the following code comments:
// Begin methods for managing global statistics for
// status report

(New method declarations)

// End methods for managing global statistics for
// status report
In addition, you must replace the calls to the myLivelink 1.0 status methods in the
RenderSection, RenderPage, StatusClear, and StatusGet functions.
Exception Message Processing
If your custom widget throws an exception that includes the exception text in addition to
the error message, you must update the code to use the WidgetUtils.jsString
JavaScript function. For example, the JBookmark 1.0 code includes the following line:
throw new WidgetError( "E__PropertiesGetEx," + e.toString() );
To upgrade the line to the myLivelink 9.0 standard, the line is modified as follows:
throw new WidgetError( "E__PropertiesGetEx," +
WidgetUtils.jsString( e.toString() ) );
Updated Log Message Format
Your custom widget code should not specify a carriage return/line feed (CRLF) for each
call to WidgetLog.Log( ). The WidgetLog.Log( ) method has been upgraded in
myLivelink 9.0 to automatically add a blank line after each line it writes to the log files.
For example, the following line of code displays a message in the Java console window in
a myLivelink 1.0 installation:
WidgetLog.log( "Testing..." + CRLF + CRLF + aVar + CRLF );
In myLivelink 9.0, you can display the same message using the following lines:
WidgetLog.log( "Testing..." );
WidgetLog.log( "" );
WidgetLog.log( aVar );
The message is also written to a log file named myLivelink_home\logs\widgetname.log,
where myLivelink_home is the myLivelink installation directory, and widgetname is your
widgets name. The log file is overwritten each time you start the widget.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
56 Livelink UNITE Widget Developer's Guide

New Notification Types Processing
myLivelink 9.0 includes new and modified notification types. You may need to modify
your custom widget to issue these new notification types, or perform a specific task if
your widget receives one of these notification types. For more information about
notification types, see Table 6-1 on page 77.
If your custom widget calls the Notify() method to notify itself that administrative
changes have been made, use the new kNotifySelf notification type (which has a
value of 11) rather than the kNotifyAdminChanges notification type (which has a
value of 8). Use the kNotifyAdminChanges notification type only to notify widgets
that myLivelink Administrative data has changed. The kNotifySelf notification type
indicates that a widgets Notify() method needs to perform special processing only
against data pertinent to the widget data type and not against myLivelink administrative
data. If your custom widget code contains a line similar to the following line from the
JBookmark 1.0 sample widget:
// Notify this widget that there were Admin changes.
Notify( kNotifyAdminChanges );
change the notification type to kNotifySelf as follows:
// Notify this widget that there were Admin changes.
Notify( kNotifySelf );
In addition, you may choose to modify your widgets Notify() method to process the
following new notification types:
kNotifySelfBackOnline
kNotifyWidgetBackOnline
kNotifySelf
If you modify your custom widget to use the kNotifySelf notification type instead of
the kNotifyAdminChanges notification type, your custom widgets Notify()method
must process the kNotifySelf notification type value so that the widgets
administrative data cache is refreshed when changes are made. Also, you may choose to
remove processing for the kNotifyAdminChanges notification type value.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 57

Test Your Widget
Before you continue upgrading your custom widget, test the upgrades you have made.
To test your custom widget upgrades:
1. At a command prompt, move to the myLivelink_WDK\java\bin directory, where
myLivelink_WDK is the directory where you installed the myLivelink 9.0 WDK.
2. Compile your widget code by entering the following at the command prompt:
makewidget widgetname
3. Copy your widgets JavaScript files to the myLivelink_home\support directory,
where myLivelink_home is the myLivelink 9.0 installation directory.
4. Copy the myLivelink_WDK\support\WidgetUtil.js file to the
myLivelink_home\support directory.
Note The WidgetUtil.js file was not modified for myLivelink 9.0.
5. Start your custom widget by entering the following at a command prompt:
debugwidget widgetname
6. Access myLivelink and confirm that the widget is operating properly.

Upgrading Custom Widgets from a myLivelink Release Pre-9.0
58 Livelink UNITE Widget Developer's Guide

View Profile Support Upgrades
A primary feature of myLivelink 9.0 views functionality is the ability to publish a profile
to a set of members. A published profile is a pre-configured, read-only set of tabs made
available on the Profiles menu for members of a view. For more information about how
to create and publish a profile, see Getting Started with myLivelink in the myLivelink
Installation and Administration Guide.
If you do not upgrade your custom widget code to include view support, the following
problems occur if your widget is deployed on a published profile:
The section configuration button appears in your custom widgets section
headers. Because sections displayed on a published profile must be read-only,
members cannot have access to a configuration button.
If your widget uses the Detach and Full-Page features (as demonstrated in the
JBookmark widget), members that click the Detach button for the detached view or
the section title link for the full-page view do not see the correct, user-configured
data. For example, a JBookmark widget that has been upgraded to support published
profiles displays the administration message as configured on the Administration
page, but not the bookmarks displayed in the section on the Front Page.
The Return to Front Page command on the Action menu on full-page view pages
returns a member to the default Front Page tab even if that was not the active tab
where the member made the request for the full-page view.
To upgrade your custom widget to support myLivelink views functionality, complete the
tasks described in the following sections.
Suppressing the Section Configuration Button
You must modify the SectionSpec.bConfig value assignment in the
RenderSection function to remove the section configuration button from your custom
widgets sections when they are published on a profile. In myLivelink 1.0, the bConfig
field is always set to TRUE so that the configuration button is always displayed in a
section header. In myLivelink 9.0, set the SectionSpec.bConfig to the
SectionSpec.bProfilesAreIdentical field. The bProfilesAreIdentical field
has the value TRUE if the members active profile is the same as his or her own profile.
The field has the value FALSE if the active profile is not the same as the members
profile, meaning that the member is displaying a published profile that contains a section
rendered by your custom widget.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 59

Retrieving Data for Detached and Full-Page Views
Several changes are required to myLivelink 1.0 custom widget code to ensure that the
proper data is retrieved from the member profile for Detached and Full -Page views.
Accessing the Profile
In your custom widgets Detached and full-page functions, use the
oReferencedProfile field rather than the oProfile field to access the members
profile. By using the oReferencedProfile field, you ensure that data is retrieved from
the member profile that owns the data. For example, myLivelink 1.0 code accessed
profile data as follows:
seqSettings = spec.oProfile.PropertyList( );
To upgrade this code to support view profiles, modify it as follows:
seqSettings = spec.oReferencedProfile.PropertyList( );
Passing the Referenced Profile Name
Your custom widget code must pass the referenced profile name on the URL of the full-
page view. This URL is specified in the RenderSection function by the
SectionInfo.wsTitleURL field. Use the NameGet() operation of the referenced
profile to get the name of the referenced profile. When constructing the URL for the
wsTitleURL field, add the following code to add the referenced profile parameter to the
URL if the members active profile is not the same as his or her own profile:
if ( ! spec.bProfilesAreIdentical )
{
str += "&ReferencedProfile=" +
spec.oReferencedProfile.NameGet();
}
To pass the referenced profile name on the URL of the Detached page view, you need to
modify line 486 in the MLLWidget_FrontPage.js file. The existing line is:
s = Page__CGI + '?Widget=' + widgetType +
'&Request=Detach&Tab=' + Page__Tab + '&Section=' +
sectionName
Modify the line as follows:
s = Page__CGI + '?Widget=' + widgetType +
'&Request=Detach&Tab=' + Page__Tab + '&Section=' +
sectionName
+ '&ReferencedProfile=' + FrontPage__StaticProfile

Upgrading Custom Widgets from a myLivelink Release Pre-9.0
60 Livelink UNITE Widget Developer's Guide

Action Menu Processing
A feature of myLivelink 9.0 is the navigation toolbar displayed on each page. The toolbar
allows members to go to the various profiles and tabs available on the myLivelink front
page. The navigation provided by the new toolbar may eliminate the need for your
custom widget to provide the Return to Front Page command on the Action menu of Full
Page pages. However, if you want the Return to Front Page command to return
members to the profile and tab they were viewing before they displayed the Full Page
page, you must modify the PageInfo.seqHeaderButtons setting in your custom
widgets Full Page render function. If the member profile and the referenced profile are
not the same, the name of the referenced profile must be specified on the buttons (menu
command) URL. In order to accommodate the referenced profile name, you must use a
new JavaScript function, Page_Submit7 rather than the Page_Submit3 function. The
following sample code from the 9.0 JBookmark sample sets
PageInfo.seqHeaderButtons:
String str = "javascript:Page_Submit7( 'FrontPage', '', " +
WidgetUtils.jsString(spec.wsTab) +
", '', '', Page__Portal, Page__PBFrontPage, ";
if ( ! spec.bProfilesAreIdentical )
{
str +=
WidgetUtils.jsString(spec.oReferencedProfile.NameGet()
);
}
else
{
str += "''";
}
str += ")";
PageInfoButton[] headerbuttons = new PageInfoButton[ 1 ];
headerbuttons[ 0 ] = new PageInfoButton(
"JBookmark__FullPageReturnToFrontPage", str );
pageInfo.seqHeaderButtons = headerbuttons;
Note The Page__Portal and Page__PBFrontPage parameters specified in the
Page_Submit () method support third-party portal products integrated
with your myLivelink installation.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 61

Test Your Widget
Access your custom widgets section on a published profile to test the upgrades you have
made.
To test your custom widget upgrades:
1. At a command prompt, move to the myLivelink_WDK\java\bin directory where
myLivelink_WDK is the directory where you installed the myLivelink 9.0 WDK.
2. Compile your widget code by entering the following at the command prompt:
makewidget widgetname
3. Copy your widgets JavaScript files to the myLivelink_home\support directory,
where myLivelink_home is the myLivelink 9.0 installation directory.
4. Copy the myLivelink_WDK\support\WidgetUtil.js file to the
myLivelink_home\support directory.
Note The WidgetUtil.js file was not modified for myLivelink 9.0.
5. Start your custom widget by entering the following at a command prompt:
debugwidget widgetname
6. Access a published profile and verify that the section is operating properly.
JavaScript and Online Help Upgrades
Your custom widgets JavaScript and online help files must be updated to conform to the
myLivelink 9.0 convention.
JavaScript Modifications
If you have properly modified your custom widget code according to the instructions in
the sections above, your custom widget is functional in myLivelink 9.0. However, there
are additional modifications that you should make to your widget to make it fully
compatible with myLivelink 9.0.
Note Open Text strongly recommends that you update your custom widget code
to include the modification described in this section.
Including Additional JavaScript Files
myLivelink automatically includes a widgets JavaScript file,
MLLWidget_ widgetname.js, where widgetname is the widgets name, and its translation
file MLLWidget_ widgetname_language.js, where language is the browser language code,
(for example, en for English) identified by myLivelink as the members preference. If
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
62 Livelink UNITE Widget Developer's Guide

your custom widget requires additional JavaScript files, set the seqJS field of the
SectionInfo or PageInfo data structures in your code instead of using JavaScript
include file syntax in the widgets JavaScript file. For example, in myLivelink 1.0 you
include the WidgetUtil.js JavaScript file by specifying the following line in the widget
JavaScript file:
document.write( '<SCRIPT LANGUAGE="JavaScript1.2" SRC="' +
Page__Support + 'WidgetUtil.js"></SCRIPT>' )
Include the JavaScript file, using the following code:
sectionInfo.seqJS = new String[ 1];
sectionInfo.seqJS[0] = spec.wsSupport + "WidgetUtil.js";
If your custom widget code uses the same naming conventions as the JBookmark sample
widget, the RenderSection Admin, Config, Detach, and FullPage functions must
be updated.
Setting the Redirect URL
Your custom widget code must specify the HTTP location to which a members browser
is redirected when an operation completes. To meet the myLivelink 9.0 convention, your
custom widget code must set the PageInfo.wsHTTPLocation field to the
PageSpec.wsNextURL field. The value of the wsNextURL field is determined by the
value of the NextURL HTML form element. The NextURL HTML form element is
assigned a value by one of the JavaScript functions described in Button Processing,
below.
If your custom widget code uses the same naming conventions as the JBookmark sample
widget, the Admin2 and Config2 functions in the RenderPage function must be
updated.
Button Processing
You should modify your widgets JavaScript file to include code that sets the redirect
URL sent to member browsers after they complete an action on a page.
Administration Pages
Add the following code to the JavaScript function that renders the Administration page.
The code sets a variable that indicates whether the member is accessing the widget
through a third-party portal product.
s += eval( Page__PortalArgs + '()' )
In the same function, add the following code that defines the redirect URL for a member
returning to the Section Administration page after clicking the Submit button on an
Administration page. Specifying the Page__NextURLtoAdminArgs variable sets the
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 63

NextURL form element properly whether the widget is used from Livelink UNITE or
from a third-party portal product.
s += eval( Page__NextURLtoAdminArgs + '()' )
In addition, you must add the following code that defines the redirect URL for a member
returning to the Section Administration page after clicking the Cancel button on an
Administration page. In myLivelink 1.0, the Cancel button redirect URL was specified
using the following code:
s += ' <INPUT TYPE="BUTTON" VALUE="' + Page__Cancel + '"
ONCLICK="javascript:Page_Submit2(\'Admin\',\'WidgetAdmin\')">'
For myLivelink 9.0, the Cancel button redirect URL is specified using the following code:
s += eval( Page__CanceltoAdminArgs + '()' )
Note If you do not call these functions or in some way assign a value to the
NextURL form element, the value of PageSpec.wsNextURL is an empty
string.
Configuration Pages
Add the following code to define the redirect URL for a member returning to the
myLivelink front page after clicking the Submit button on a configuration page:
s += eval( Page__NextURLArgs + '()' )
Specifying the Page__NextURLArgs variable sets the NextURL form element properly
whether the widget is used from myLivelink or from a third-party portal product. If this
form element is not defined, the value of PageSpec.wsNextURL is an empty string.
Also, you must add the following code that defines the redirect URL for a member
returning to the myLivelink front page after clicking the Cancel button on a
configuration page. In myLivelink 1.0, the Cancel button redirect URL was specified
using the following code:
s += '<INPUT TYPE="BUTTON" VALUE="' + Page__Cancel + '"
ONCLICK="javascript:Page_Submit4( \'FrontPage\', \'\',
Page__Tab, Page__Section )">&nbsp;'
For myLivelink 9.0, the Cancel button redirect URL is specified using the following code:
s += eval( Page__CancelArgs + '()' )
In addition, you must replace the code that specifies the redirect URL supplied when a
member clicks the Delete Section button. For example in myLivelink 1.0, the Delete
Section redirect URL was specified as follows for the sample widgets:
s += '<INPUT TYPE="BUTTON" VALUE="' + Page__DeleteSection + '"
ONCLICK="javascript:widgetname_ConfigDeleteSection()">'
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
64 Livelink UNITE Widget Developer's Guide

where widgetname is JBookmark. For Livelink UNITE 9.0, the Delete Section button URL
is specified using the following code:
s += eval( Page__DeleteSectionArgs + '(
"widgetname_ConfigDeleteSection()" )' )
Administration and Configuration Page Descriptions
In myLivelink 1.0, Administration and Configuration page descriptions were specified
using the following code:
Page_Description( JS_variable )
where JS_variable is the string variable assigned the value of the page description. To
generate page descriptions in myLivelink 9.0, use the following code:
eval( Page__FormatDescription + '( JS_variable )' )
Update HTML Form Definitions
You should update each <FORM> tag definition in the widget JavaScript file to include
the TARGET=_top element. The following <FORM> tag from the JBookmark sample
widget follows the myLivelink 9.0 convention:
s += '<FORM NAME="JBookmarkAdminForm" ACTION="' + Page__CGI +
'" METHOD="POST" TARGET="_top">'
New Page_Write () Method
myLivelink 9.0 includes support for a new JavaScript function, Page_Write(), that
writes data to the browser. Replace all instances of the native JavaScript method
document.write() with the Page_Write() function. For example, the following
JavaScript writes the message Hello World to the browser:
var s
s = Hello World
document.write(s)
To make your custom widget follow the myLivelink 9.0 convention, you modify the
JavaScript to use the Page_Write() function as follows:
var s
s = Hello World
Page_Write(s)
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 65

Defining the Section Title Input Box
Upgrade your widgets JavaScript to include the myLivelink 9.0 convention for defining
the Section Title input box on the widgets Configuration page. In myLivelink 1.0, the
input box was defined as follows:
s += '<TR>'
s += ' <TD>'
s += ' <TABLE WIDTH="100%" CELLPADDING="3" CELLSPACING="0"
BORDER="0">'
s += ' <TR>'
s += ' <TD NOWRAP ALIGN="CENTER" CLASS="A2B">' +
Page__SectionTitle + ':&nbsp;'
s += ' <INPUT NAME="SectionTitle" SIZE="26"
MAXLENGTH="64" VALUE="' + widgetname__MemberSectionTitle + '"
ONFOCUS="this.select()" ONCHANGE="javascript:Page_DirtySet()">'
s += ' </TD>'
s += ' </TR>'
s += ' </TABLE>'
s += ' </TD>'
s += '</TR>'
For myLivelink 9.0, define the section title input box, using the following code:
s += eval( Page__SectionTitleArgs + '
( widgetname__MemberSectionTitle )' )
jsQuote and jsString Function Usage
In the myLivelink WDK 1.0, the jsQuote() function ensured that strings were properly
escaped when used as JavaScript parameters passed from the widget code. However, the
Java version of the jsQuote() function did not escape HTML tags. The behavior of the
jsQuote() function is modified in the myLivelink WDK 9.0 to behave in the same way
as the Java version; it does not escape HTML tags. The myLivelink 9.0 WDK includes a
new function , jsString(), that escapes the same characters that the
jsQuote()function escapes plus the significant HTML tag characters. The modification
of the jsQuote() function in the myLivelink WDK 9.0 may affect the way myLivelink
displays your custom widgets data. For more information about the jsQuote() and
jsString() functions, review the use of jsQuote() in your Java custom widget.
Depending on the kind of data your widget generates, your widget code may require the
functionality provided by the jsString() function. The JBookmark sample widget was
modified for myLivelink 9.0 to use the jsString() function exclusively, but this may
not be the correct choice for your widget.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
66 Livelink UNITE Widget Developer's Guide

Choosing a Function
Based on the value and purpose of the data your widget generates for display in
myLivelink, you will have to decide whether to use the jsQuote() or jsString()
function. Your widget code may include both functions.
HTML Tags Interpreted in myLivelink
Use the jsQuote() function if you want HTML tags to be interpreted when displayed
in myLivelink. For example, HTML tags should be interpreted when the data to be
displayed in a section contains HTML formatting such as <I> and </I> to italicize text.
If your myLivelink 9.0 custom widget code uses the jsQuote() function around the
data to pass it as a JavaScript parameter, the function does not escape the HTML
tags, so the JavaScript function receives the data, including the <I> and </I> tags.
When the data is displayed in myLivelink, the text enclosed in the tags is displayed
in italic font.
If your myLivelink 9.0 custom widget code uses the jsString() function around
the data to pass it as a JavaScript parameter, the jsString() function escapes the
HTML tags, so the JavaScript function receives the data, including &lt;I&gt; and
&lt;/I&gt;. When the data is displayed in myLivelink, the text appears between
the escaped characters.
HTML Tags Treated as Data in myLivelink
Use the jsQuote() function if you want HTML tags to be treated as plain text within a
JavaScript function. An example where HTML tag characters should be treated as plain
text is when a data field passed as a JavaScript parameter needs to be evaluated within
the JavaScript function. For example, if the widget data passed as a JavaScript parameter
is the string < 100 and the JavaScript code needs to evaluate the value of the parameter,
the JavaScript function must receive the data as plain text.
If your myLivelink 9.0 custom widget code uses the jsQuote() function around the
string to pass it as a JavaScript parameter, the function does not escape the <
character, so the JavaScript function receives the data as < 100.
If your myLivelink 9.0 custom widget code uses the jsString() function around
the string to pass it as a JavaScript parameter, the function escapes the < character
and the JavaScript receives the data as &lt; 100.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 67

HTML Tags Displayed as Plain Text in myLivelink
Use the jsString() function if you want HTML tag characters to be displayed in
myLivelink as plain text and not interpreted as HTML. An example of when HTML tag
characters should not be interpreted is when you pass a title or description as a
parameter to a JavaScript function, as is done in the JBookmark sample widget. For
example, if users enter a bookmark name <HTML> Reference, they expect to see the
name exactly as they entered it.
If your myLivelink 9.0 custom widget code uses the jsString() function around
the bookmark name to pass it as a JavaScript parameter, the jsString() function
escapes the HTML tag characters and the JavaScript receives the string as
&lt;HTML&gt; Reference. The bookmark name displayed in Livelink UNITE is
<HTML> Reference, since &lt; and &gt; are properly interpreted as characters by
the browser.
If your myLivelink 9.0 custom widget code uses the jsQuote() function around the
name of the bookmark to pass it as a JavaScript parameter, the jsQuote() function
does not escape the HTML tag characters and the JavaScript function receives the
bookmark name as <HTML> Reference. The bookmark name is displayed in
myLivelink as Reference, since <HTML> is interpreted as an HTML tag.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
68 Livelink UNITE Widget Developer's Guide

Help File Upgrades
The myLivelink 9.0 online help system includes new functionality that is not compatible
with Livelink UNITE 1.0 help files. If you attempt to access your custom widgets online
help files without upgrading them, you receive the Object Expected JavaScript error.
You must upgrade each online help file in your custom widget.
Also, the HTML styles used in myLivelink 1.0 online help files have been deprecated in
myLivelink 9.0. The myLivelink 1.0 HTML styles are supported in myLivelink 9.0, but
support may be removed in future releases.
To upgrade your custom widgets online help:
1. Edit an online help file.
2. Locate the following line, specified between the <HEAD> and </HEAD> tags:
<script language="JavaScript1.2" SRC="../../../MLLHelp_en.js"></script>
Note: the line may break on to a second line.
3. Replace the line with the following three lines:
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<script language="JavaScript1.2" SRC="../HelpLanguage.js"></script>
<script language="JavaScript1.2" SRC="../../../MLLHelp.js"></script>
4. Upgrade the HTML styles in the online help file to myLivelink 9.0 HTML styles by
performing global search and replace actions on the text strings specified in the
table below.

Search for (myLivelink 1.0 style) Replace with (myLivelink style)
class=docbody class=body
class=docbold class=gui
class=docitalic class=guvar
class=docinf class=infin
class=dochead class=subh1
class=doctoprel class=subh2
class=docnote class=gui
5. Save your changes and close the file.
6. Repeat steps 1 to 5 for each online help file.
Upgrading Custom Widgets from a myLivelink Release Pre-9.0
Upgrading Custom Widgets 69

After you update your custom widgets online help files, copy them into the
myLivelink_home\support\help\language\widget_name directory, where myLivelink_home
is the myLivelink installation directory, language is the help file language code (for
example, en), and widget_name is the name of your custom widget. You can access the
online help by clicking the For this Page command on the Help menu.


Upgrading Custom Widgets from a myLivelink Release Pre-9.0
70 Livelink UNITE Widget Developer's Guide


71

Chapter Six
Livelink UNITE IDL Reference
Livelink UNITE widgets are the request handler objects in Livelink UNITE; they are the
interface to any content provider presented through Livelink UNITE. Widgets conform to
Livelink UNITEs widget Interface Definition Language (IDL) specification. This section
explains Livelink UNITEs widget IDL specification.
Widget Interface, page 72
Widget_SectionCallback Interface, page 83
Widget Data Structures, page 84
Widget Exceptions, page 114
Profile Interface, page 116
Profile Data Structures, page 135
Profile Exceptions, page 145
System Log Writer Interface, page 146

Widget Interface
72 Livelink UNITE Widget Developer's Guide

Widget Interface
Livelink UNITEs Widget interface defines a widgets required methods.
Important Widget code must contain a method for each Widget interface operation
(even if the corresponding method provides no functionality). If a
corresponding method does not appear for each Widget interface operation,
CORBA communication errors may occur.
The Widget interface contains the following operations:
RenderSection
RenderPage
StatusGet
StatusClear
Notify
Ping
Destroy
RenderRawPage
RenderProgressivePage
Widget Interface
Livelink UNITE IDL Reference 73

RenderSection
A widgets RenderSection operation fulfills a request from the Livelink UNITE
extension to provide the functionality and content in a Livelink UNITE section. The
RenderSection operation is called each time a member requests an action from the
widgets corresponding section.
The RenderSection operation is a one-way operation; that is, Livelink UNITE does not
wait for the operation to return a value. Instead, the operation relies on a callback feature
of the SectionSpec data structure it receives with the request to perform processing to
properly return results to Livelink UNITE.
IDL Syntax
oneway void RenderSection( in SectionSpec spec );
Parameter
spec a SectionSpec data structure that contains request and member
information passed from Livelink UNITE to the widget. For
more information about the SectionSpec data structure, see
SectionSpec, page 88.
Exceptions
The RenderSection operation does not throw exceptions, because no information can be
passed through an exception. If an error is encountered, Open Text recommends that the
widgets RenderSection operation returns JavaScript code that displays an appropriate
error message in the widgets section.
Widget Interface
74 Livelink UNITE Widget Developer's Guide

RenderPage
A widgets RenderPage operation fulfills a request from Livelink UNITE to provide the
functionality and content in a Livelink UNITE page. The RenderPage operation is called
each time a member requests an action from the widgets corresponding page. A
widgets RenderPage operation must handle Admin and Config requests, and optionally,
Detach.
IDL Syntax
PageInfo RenderPage( in PageSpec spec ) raises ( WidgetError );
Parameter
spec A PageSpec data structure that contains request and member
information passed from the Livelink UNITE server to the
widget. For more information about PageSpec, see PageSpec,
page 101.
Return Value
PageInfo A PageInfo data structure that contains all the content in a
Livelink UNITE page. For more information about PageInfo, see
PageInfo, page 93.
Exception
WidgetError If RenderPage encounters an error, it returns an exception. For
more information about Livelink UNITE exceptions, see Widget
Exceptions, page 114.
Widget Interface
Livelink UNITE IDL Reference 75

StatusGet
The StatusGet operation provides the status of a widget.
IDL Syntax
StatusSeq StatusGet( in long lKind );
Parameter
lKind A long integer that specifies the type of status requested.
Return Value
StatusSeq A sequence of Livelink UNITE Status data structures that
contain widget status information. For more information about
the Status data structure, see Status, page 111.
Widget Interface
76 Livelink UNITE Widget Developer's Guide

StatusClear
The StatusClear operation resets the status values maintained by the widget.
IDL Syntax
void StatusClear( in long lKind );
Parameter
lKind A long integer that specifies the kind of status values to reset.
Widget Interface
Livelink UNITE IDL Reference 77

Notify
The Notify operation notifies a widget when administrative and other data changes. A
widgets Notify operation is invoked when Livelink UNITE starts and reinitializes, and
in response to other system and widget events. For example, your widget may not
require any action when it is notified that Livelink UNITE administrative settings have
changed, but it may need to perform some task when the widget administrative settings
are modified; such as reinitializing the widgets internal caches.
IDL Syntax
void Notify(in long lKind);
Parameter
lKind A long integer that specifies the notification type
Notification Types
The following table explains the Livelink UNITE notification types:
Table 6-1: Notification Types
Value Indicates
0 A generic notification
1 Livelink UNITE has initialized.
2 Livelink UNITE has started.
3 Livelink UNITE profiles are available.
4 Livelink UNITE profiles have been restored.
5 A widget group has changed. For example, the Livelinks widget has been
updated; so any widget that exposes Livelink data should refresh its list of
Livelink sites.
6 A widget has registered with the Livelink UNITE Naming service.
7 A widgets cache has been updated (for example, the NewsCache).
8 Livelink UNITE administrative data has changed.
9 This widget had been moved offline and is now back online.
10 A widget that had been moved offline is now back online.
11 This widgets administrative data has changed.

Widget Interface
78 Livelink UNITE Widget Developer's Guide

If you want to make your widgets Notify method code more meaningful, you can define
constants that describe the notification values. For example, the Livelink UNITE sample
widgets define the following constants:
kNotifyGeneric = 0;
kNotifySystemInitialize = 1;
kNotifySystemStartup = 2;
kNotifyProfilesAvailable = 3;
kNotifyProfilesRestored = 4;
kNotifyWidgetGroupChanged = 5;
kNotifyWidgetRegistered = 6;
kNotifyCacheUpdated = 7;
kNotifyAdminChanges = 8;
kNotifySelfBackOnline = 9;
kNotifyWidgetBackOnline = 10;
kNotifyNotifySelf = 11;
Widget Interface
Livelink UNITE IDL Reference 79

Ping
The Ping operation is used to confirm that a widget is active and accessible to the
Livelink UNITE server. The Ping operation performs no action. Livelink UNITE assumes
a widget is available as long as a request to execute the widgets Ping operation does not
create a CORBA communication or some other kind of error.
IDL Syntax
void Ping ();
Widget Interface
80 Livelink UNITE Widget Developer's Guide

Destroy
The Destroy operation deletes an instance of a widget object.
Important Use of the Destroy operation is not supported in this release of Livelink
UNITE. However, an empty Destroy() method in your widget code is
required to account for the presence of the Destroy operation in Livelink
UNITEs widget IDL specification.
IDL Syntax
void Destroy ();
Widget Interface
Livelink UNITE IDL Reference 81

RenderRawPage
Important The RenderRawPage operation is for Open Text internal use only. However, a
RenderRawPage() method in your widget code is required to account for the
presence of the RenderRawPage operation in Livelink UNITEs widget IDL
specification. The operation should return NULL.
IDL Syntax
PageInfo RenderRawPage( in PageSpec spec )
raises ( WidgetError );

Widget Interface
82 Livelink UNITE Widget Developer's Guide

RenderProgressivePage
Important The RenderProgressivePage operation is for Open Text internal use only.
However, a RenderProgressivePage() method in your widget code is
required to account for the presence of the RenderProgressivePage operation
in Livelink UNITEs widget IDL specification. The operation should return
NULL.
IDL Syntax
MLLCallBack::CallBack RenderProgressivePage( in PageSpec spec )
raises ( WidgetError );
Widget_SectionCallback Interface
Livelink UNITE IDL Reference 83

Widget_SectionCallback Interface
The Widget_SectionCallback interface contains a single operation,
RenderSectionCallback.
RenderSectionCallback
The RenderSectionCallback operation returns to the Livelink UNITE server the section
content information compiled by a widgets RenderSection operation.
IDL Syntax
oneway void RenderSectionCallback( in SectionInfo SectionInfo );
Parameter
SectionInfo The SectionInfo data structure that contains the section content
information compiled by the widget for display in Livelink
UNITEs front page.
Widget Data Structures
84 Livelink UNITE Widget Developer's Guide

Widget Data Structures
The Livelink UNITE widget IDL specification defines a number of data structures and
exceptions. Data structures are used to pass information between the Livelink UNITE
extension and widgets. Exceptions define an error condition encountered by a widget.
There are five kinds of data structures and exceptions:
Section
Page
Request
Status
General
Widget Data Structures
Livelink UNITE IDL Reference 85

Section Data Structures
Livelink UNITE section data structures are passed between the widget and Li velink
UNITE during section-rendering transactions. Livelink UNITE section data structures
are:
SectionInfo
SectionPage
SectionSize
Widget Data Structures
86 Livelink UNITE Widget Developer's Guide

SectionInfo
The SectionInfo data structure is an IDL structure that defines the content and behavior
of a Livelink UNITE section. The SectionInfo data structure is created by a widgets
RenderSection operation. It is returned to the Livelink UNITE extension through a
callback function specified in the SectionSpec data structure passed in each
RenderSection request.
Setting Fields
Every field in the SectionInfo data structure must contain at least a null string or null
value. If you do not assign at least a null string or null value to each field, a CORBA error
occurs when the data structure is passed to the Livelink UNITE extension.
IDL Definition
struct SectionInfo
{ long lSectionIndex;
wstring wsTitle;
wstring wsTitleURL;
boolean bConfig;
boolean bDetach;
long lDetachWidth;
long lDetachHeight;
wstring wsData;
WStringSeq seqJS; };
Fields
Table 6-2: SectionInfo Fields
Field Use
lSectionIndex The location (in order of appearance) on the Livelink UNITE tab
where the section appears. This value indicates to the Livelink
UNITE extension where the content generated by a widget is
displayed.
wsTitle The text displayed in the section title bar
wsTitleURL A hypertext reference applied to the section title. If the section title is
not a hyperlink, supply a null string in this feature.
bConfig Indicates whether the section provides a configuration page. Specify
FALSE if the section does not provide a configuration page. If the
value is set to TRUE, Livelink UNITE adds the Edit button to the
section title bar, with a Request=Config link that must be handled by
the widgets RenderSection operation.
Widget Data Structures
Livelink UNITE IDL Reference 87

Table 6-2: SectionInfo Fields
Field Use
bDetach Indicates whether the section can be detached from the Livelink
UNITE front page. Specify FALSE if members cannot detach the
section; TRUE if members can detach the section. If the value is set to
TRUE, Livelink UNITE adds the Detach button to the section title
bar. When members click the Detach button, Livelink UNITE sends
a specific request Request=Detach that must be handled by the
widgets RenderPage operation.
lDetachWidth The width of the section window displayed when it is detached from
the Livelink UNITE front page
lDetachHeight The height of the section window when it is detached from the
Livelink UNITE front page
wsData The content of the section specified in JavaScript functions
seqJS JavaScript support files required by the section in addition to a
widgets default JavaScript file. These additional files must be stored
in the Livelink UNITE support directory. By default, Livelink UNITE
includes the JavaScript files MLLWidget_name.js and
MLLWidget_ name_language.js, where name is the widget name and
language is the browser accept language. For more information about
the WStringSeq data structure used in this feature, see WStringSeq,
page 113.
Widget Data Structures
88 Livelink UNITE Widget Developer's Guide

SectionSpec
The SectionSpec data structure is an IDL structure created and passed by the Livelink
UNITE extension to a widget in a request to render a section with the RenderSection
operation.
IDL Definition
struct SectionSpec
{ long lRequestID;
wstring wsTab;
wstring wsSection;
WStringSeq seqLanguages;
RequestCookieSeq seqCookies;
boolean bDomainsEnabled;
wstring wsDomain;
boolean bSiteDomain;
MLLProfile::Profile oSystemProfile;
MLLProfile::Profile oProfile;
MLLProfile::Profile oReferencedProfile;
boolean bProfilesAreIdentical;
boolean bSignedIn;
wstring wsKeyPath;
MLLProfile::ProfileValueSeq seqSectionSettings;
SectionSize Size;
long lSectionIndex;
wstring wsProtocol;
wstring wsHostName;
wstring wsCGI;
wstring wsSupport;
LLSysLogWriter::Writer oLogWriter;
wstring wsLogSettings;
Widget_SectionCallback oCallback; };
Fields
Table 6-3: SectionSpec Fields
Field Use
lRequestID A unique Integer that identifies the request
wsTab The tab ID where the widgets section is displayed
wsSection The widgets section ID
seqLanguages A sequence of common accept languages supported by the
browser and Livelink UNITE. For more information about the
WStringSeq data structure, see WStringSeq, page 113.
Widget Data Structures
Livelink UNITE IDL Reference 89

Table 6-3: SectionSpec Fields
Field Use
seqCookies A sequence of cookies passed from the members browser to the
widget. For more information about the RequestCookiesSeq data
structure, see RequestCookieSeq, page 109.
bDomainsEnabled Indicates whether the Livelink UNITE installation is enabled for
domains. The value is TRUE if domains are enabled; FALSE if
they are not enabled.
wsDomain The current domain
bSiteDomain Indicates whether the current domain is the LivelinkUNITE_Site
domain. The value is TRUE if the current domain is the
LivelinkUNITE_Site domain; FALSE if it is not.
oSystemProfile The domains system profile. For more information about the
Livelink UNITE system profile, see System Profile, page 27.
oProfile The members Livelink UNITE profile. For more information
about Livelink UNITE member profiles, see Member Profiles,
page 26.
oReferencedProfile The members active profile. If the active profile is the members
My Profile, the object in this field is equivalent to the object in
the oProfile field.
bProfilesAreIdentical Indicates whether the referenced profile and the members
profile are the same. The value is TRUE if the profiles are the
same; FALSE if the profiles are not the same.
bSignedIn The members sign-in status. The value is TRUE if the member is
signed in; FALSE if the member is not signed in.
wsKeyPath The section key path. The section key path is a string comprised
of the section and tab IDs.
seqSectionSettings A sequence of all tab and section IDs from a member profile. For
more information about the ProfileValue data structure, see
ProfileValue, page 136.
Size A value from the SectionSize enumeration that indicates the size
of the section. For more information about the SectionSize
enumeration, see SectionSize, page 91.
lSectionIndex The location (in order of appearance) on the Livelink UNITE tab
where the section appears. This value indicates to Livelink
UNITE where the content generated by a widget is displayed.
wsProtocol The protocol (for example, HTTP or HTTPS) of the incoming
Web request
Widget Data Structures
90 Livelink UNITE Widget Developer's Guide

Table 6-3: SectionSpec Fields
Field Use
wsHostName The host name and port of the computer where the incoming
Web request originated (for example, myServer:4000)
wsCGI The virtual directory and extension for the Livelink UNITE
server. For example, in many Livelink UNITE installations wsCGI
is set to /myLivelink/myLivelink.dll.
wsSupport The virtual directory of Livelink UNITE support files. For
example, the virtual directory to Livelink UNITE support files
may be /myLivelinkSupport/.
oLogWriter The members Livelink UNITE log writer object. For more
information about Livelink UNITE log writer objects, see
System Log Writer, page 29.
wsLogSettings The log settings as specified by the Administrator in the
Windows registry. The log settings indicate what information
the widget writes to a log file. For more information about log
settings, see Log Settings, page 29.
oCallback The callback operation that returns to Livelink UNITE the
SectionInfo data structure that contains the section content
compiled by the widgets RenderSection operation. For more
information about the callback operation, see
Widget_SectionCallback Interface, page 83.
Widget Data Structures
Livelink UNITE IDL Reference 91

SectionSize
The SectionSize data structure is an IDL enumeration that specifies the size of the
section displayed on Livelink UNITEs front page. The values are part of the
SectionSpec data structure passed from the Livelink UNITE server, with a request to the
widget to perform the RenderSection operation.
IDL Definition
enum SectionSize{ kThin, kWide };
Fields
Table 6-4: SectionSize Fields
Value Specification
kThin The section is a thin section displayed in the left or right column of
Livelink UNITEs front page.
kWide The section is a wide section displayed in the center column of
Livelink UNITEs front page.
Widget Data Structures
92 Livelink UNITE Widget Developer's Guide

Page Data Structures
Livelink UNITE page data structures are passed between the widget and the Livelink
UNITE system during page-rendering transactions. The Livelink UNITE page data
structures are:
PageInfo
PageInfoButton
PageInfoButtonSeq
PageInfoCookie
PageInfoCookieSeq
PageInfoCookieStatus
PageSpec
PageInfoHeaderType
Widget Data Structures
Livelink UNITE IDL Reference 93

PageInfo
The PageInfo data is an IDL structure that defines the content and behavior of a Livelink
UNITE page. The RenderPage operation returns the PageInfo data structure to the
Livelink UNITE server. For more information about the RenderPage operation, see
RenderPage, page 74.
Setting Fields
Every field in the PageInfo data structure must contain at least a null string or null value.
If the widget does not assign at least a null string or null value to each field, a CORBA
error occurs when the data structure is passed to the Livelink UNITE extension.
IDL Definition
struct PageInfo
{ wstring wsHTTPLocation;
PageInfoCookieSeq seqHTTPCookies;
long lMetaRefresh;
boolean bDetached;
wstring wsPageTitle;
wstring wsHeaderIMG;
wstring wsHeaderALT;
wstring wsHeaderTitle1;
wstring wsHeaderTitle2;
PageInfoHeaderType HeaderType;
wstring wsHelpURL;
PageInfoButtonSeq seqHeaderButtons;
boolean bAds;
wstring wsData;
WStringSeq seqJS; };
Fields
Table 6-5: PageInfo Fields
Field Use
wsHTTPLocation The URL to the location (often the Livelink UNITE front page tab or
Administration page) where a members browser is redirected after
the operation finishes processing
seqHTTPCookies Cookies added to the browser of a member who requests the
RenderPage operation. For more information about PageInfoCookie
structures, see PageInfoCookie, page 98.
Widget Data Structures
94 Livelink UNITE Widget Developer's Guide

Table 6-5: PageInfo Fields
Field Use
lMetaRefresh The refresh rate (in seconds) for the page. A value of 0 indicates that
no refresh occurs. A value of 1 indicates that the refresh rate a
member sets on Livelink UNITEs Administration page is used. A
value greater than zero indicates the refresh rate in seconds.
bDetached Indicates whether the page appears in a separate window from
Livelink UNITE. Specify TRUE if the page is detached; FALSE if it is
not. If the page is detached, Livelink UNITE adds a Cancel button to
the page footer that provides a way for members to close the page.
wsPageTitle A JavaScript variable or function that returns the page title displayed
in the browser title bar
wsHeaderIMG The URL to a custom image displayed on the left side of the page
header. Specify a null string () to display the default image .
wsHeaderALT Alternate text for a custom page header image.
wsHeaderTitle1 A JavaScript variable or function that returns the primary page title
displayed in the page header
wsHeaderTitle2 A string displayed in the secondary page title area of the page
header. The secondary page title appears in smaller, boldface type
below the page title.
HeaderType A value from the PageInfoHeaderType enumeration that specifies the
type of page header to use. For more information about
PageInfoHeaderType enumeration, see "PageInfoHeaderType, page
104
wsHelpURL The URL to the page online help applied to the For This Page
command on the Help menu. If a null string is specified, the
following URL is used by default:
http://mylivelinksupport/lang_code/MLLWidget_name/request.html
where lang_code is the language code, name is the widget name, and
request is the request name. For more information about widget
online help files, see Widget Online Help, page 23.
seqHeaderButtons A sequence of PageInfoButton data structures that define custom
commands displayed on the pages Action menu. If an empty array
is specified, the Action menu is not displayed. For more information
about PageInfoButton data structures, see PageInfoButton, page
96.
Widget Data Structures
Livelink UNITE IDL Reference 95

Table 6-5: PageInfo Fields
Field Use
bAds Indicates whether the banner advertisements displayed on the front
page are displayed on the page. Specify TRUE if banner
advertisements appear on the page; FALSE if banner advertisements
do not appear on the page.
wsData The content of the page specified in JavaScript functions
seqJS JavaScript support files required by the section in addition to a
widgets default JavaScript file. These additional files must be stored
in the Livelink UNITE support directory. By default, Livelink UNITE
includes the JavaScript files MLLWidget_name.js and
MLLWidget_ name_language.js where name is the widget name and
language is the browser accept-language. For more information about
the WStringSeq data structure used in this feature, see WStringSeq,
page 113.
Widget Data Structures
96 Livelink UNITE Widget Developer's Guide

PageInfoButton
The PageInfoButton data structure is an IDL structure that defines optional commands
displayed on a pages Action menu. PageInfoButton data structures are passed to
Livelink UNITE as part of the page definition specified in the PageInfo data structure.
IDL Definition
struct PageInfoButton{ wstring wsTitle; wstring wsHREF; };
Fields
Table 6-6: PageInfoButton Fields
Field Use
wsTitle A JavaScript function or variable that returns the command name
wsHREF The hypertext link assigned to the command
Widget Data Structures
Livelink UNITE IDL Reference 97

PageInfoButtonSeq
The PageInfoButtonSeq data structure is an IDL sequence of PageInfoButton data
structures. The PageInfoButtonSeq data structure is a container for all PageInfoButton
data structures in a widgets page definition. For more information about use of the
PageInfoButtonSeq data structure, see the description in Table 6-5 page 93.
IDL Definition
typedef sequence< PageInfoButton > PageInfoButtonSeq;
Widget Data Structures
98 Livelink UNITE Widget Developer's Guide

PageInfoCookie
The PageInfoCookie data structure is an IDL structure that defines a cookie returned to
the requesting members browser each time the widget performs the RenderPage
operation. PageInfoCookie data structures are passed to Livelink UNITE as part of the
page definition specified in the PageInfo data structure.
IDL Definition
struct PageInfoCookie
{ wstring wsName;
wstring wsValue;
PageInfoCookieStatus Status; };
Fields
Table 6-7: PageInfoCookie Fields
Field Use
wsName The cookie name
wsValue The cookie
Status A value from the PageInfoCookieStatus enumeration that indicates
the cookies status. For more information about the status values
defined in the PageInfoCookieStatus data structure, see
PageInfoCookieStatus, page 100.
Widget Data Structures
Livelink UNITE I DL Reference 99

PageInfoCookieSeq
The PageInfoCookieSeq data structure is an IDL sequence of PageInfoCookie data
structures. The PageInfoCookieSeq data structure stores all PageInfoCookie data
structures returned to the members browser each time the RenderPage operation is
called. For more information about the use of the PageInfoCookie data structure, see the
description in Table 6-5 page 93.
IDL Definition
typedef sequence< PageInfoCookie > PageInfoCookieSeq;
Widget Data Structures
100 Livelink UNITE Widget Developer's Guide

PageInfoCookieStatus
The PageInfoCookieStatus data structure is an IDL enumeration that defines cookie
status values. The values are part of the cookie definition as specified in the
PageInfoCookie data structure. For more information about the PageInfoCookie data
structure, see PageInfoCookie, page 98.
IDL Definition
enum PageInfoCookieStatus { kPermanent,
kTemporary,
kExpire,
kTemporaryNoEncrypt};
Values
Table 6-8: PageInfoCookieStatus Values
Value Specification
kPermanent The cookie is permanently stored in the members browser.
kTemporary The cookie is deleted when the members browser closes.
kExpire The cookie is deleted immediately.
KTemporaryNoEncrypt The cookie is deleted when the members browser closes and
data is not encrypted.
Widget Data Structures
Livelink UNITE IDL Reference 101

PageSpec
The PageSpec data structure is an IDL structure created and passed by the Livelink
UNITE extension to a widget in a request to render a page with the RenderPage
operation. For more information about the RenderPage operation, see RenderPage,
page 74.
IDL Definition
struct PageSpec
{ long lRequestID;
wstring wsRequest;
wstring wsTab;
wstring wsSection;
WStringSeq seqLanguages;
RequestCookieSeq seqCookies;
wstring wsNextURL;
boolean bDomainsEnabled;
wstring wsDomain;
boolean bSiteDomain;
MLLProfile::Profile oSystemProfile;
MLLProfile::Profile oProfile;
MLLProfile::Profile oReferencedProfile;
boolean bProfilesAreIdentical;
boolean bSignedIn;
RequestArgsSeq seqArgs;
wstring wsProtocol;
wstring wsHostName;
wstring wsCGI;
wstring wsSupport;
wstring wsPrivileges;
LLSysLogWriter::Writer oLogWriter;
wstring wsLogSettings;};
Fields
Table 6-9: PageSpec Fields
Field Use
lRequestID A unique Integer that identifies the request
wsRequest Specifies the page function a widget performs. For example, a
widget may provide page functions like Config or Detach.
wsTab The tab ID where the widgets section is displayed.
wsSection The widgets section ID
Widget Data Structures
102 Livelink UNITE Widget Developer's Guide

Table 6-9: PageSpec Fields
Field Use
seqLanguages A sequence of common accept languages supported by the
browser and Livelink UNITE. For more information about the
WStringSeq data structure, see WStringSeq, page 113.
seqCookies A sequence of cookies passed from the members browser to the
widget. For more information about the RequestCookiesSeq data
structure, see RequestCookieSeq, page 109.
wsNextURL The URL to the location where a members browser is redirected
after an operation finishes processing.
bDomainsEnabled Indicates whether the Livelink UNITE installation is enabled for
domains. The value is TRUE if domains are enabled; FALSE if
they are not enabled.
wsDomains The current domain
bSiteDomain Indicates whether the current domain is the myLivelink_Site
domain. The value is TRUE if the current domain is the
myLivelink_Site domain; FALSE if it is not.
oSystemProfile The domains system profile. For more information about
Livelink UNITE profiles, see Profiles, page25.
oProfile The members Livelink UNITE profile. For more information
about Livelink UNITE profiles, see Profiles, page 25.
oReferencedProfile The members active profile. If the active profile is the members
My Profile, the object in this field is equivalent to the object in
the oProfile field.
bProfilesAreIdentical Indicates whether the referenced profile and the members
profile are the same. The value is TRUE if the profiles are the
same; FALSE if the profiles are not the same.
bSignedIn The members sign-in status. The value is TRUE if the member is
signed in; FALSE if the member is not signed in.
seqArgs A sequence of arguments included in the request. Arguments
are key-value pairs from the request URL and any posted data.
For more information about the requestArgs data structure, see
RequestArgs, page 106.
wsProtocol The protocol (for example, HTTP or HTTPS) of the incoming
Web request
wsHostName The host name and port of the computer where the incoming
Web request originated (for example, myServer:4000)
Widget Data Structures
Livelink UNITE IDL Reference 103

Table 6-9: PageSpec Fields
Field Use
wsCGI The virtual directory and extension for the Livelink UNITE
server. For example, in many Livelink UNITE installations
wsCGI is set to /myLivelink/myLivelink.dll.
wsSupport The virtual directory of Livelink UNITE support files. For
example, the virtual directory to Livelink UNITE support files
may be /myLivelinkSupport/.
wsPrivileges The members privileges. Legal values for privileges are: L
sign-in enabled, G - guest, F full member privileges, including
ability to modify member privileges, R group administrator of
at least one group, U add member privileges, and A -
administrator privileges. Any combination of these values can be
assigned to a member. For example, a member with full
privileges has a value of AUFL. Multiple privilege values for a
single member can appear in any order.
oLogWriter The Livelink UNITE log writer object. For more information
about Livelink UNITE log writer objects, see System Log
Writer, page 29.
wsLogSettings The log settings as specified by the Administrator in the
Windows registry. The log settings indicate what information
the widget writes to a log file. For more information about log
settings, see Log Settings, page 29.
Widget Data Structures
104 Livelink UNITE Widget Developer's Guide

PageInfoHeaderType
The PageInfoHeaderType data structure is an IDL enumeration that defines page header
type values. The values are specified as part of the widgets page definition in the
PageInfo data structure. For more information about the PageInfo data structure, see
PageInfo, page 93.
IDL Definition
enum PageInfoHeaderType { kNormal, kFrontPage };
Values
Table 6-10: PageInfoHeaderType Values
Value Specification
kNormal The page has a normal header.
kFrontPage The page has a front-page header. The front-page header includes all
the features of your Livelink UNITE front page. For example, the
default front-page header includes banner advertisements and the
information ticker.
Widget Data Structures
Livelink UNITE IDL Reference 105

Request Data Structures
Request data structures contain arguments passed to a widget in the PageSpec data
structure. The request data structures are:
RequestArgs
RequestArgsSeq
RequestCookie
RequestCookieSeq
Widget Data Structures
106 Livelink UNITE Widget Developer's Guide

RequestArgs
The RequestArgs data structure is an IDL structure that contains arguments received in
a request. Arguments are key-value pairs from the request URL and any posted data. For
example, in the following URL Widget=Admin and TimeOfDay=1 are valid key-value
arguments:
http://host/mylivelink/mylivelink.dll?Widget=Admin&TimeOfDay=1
Common Livelink UNITE key-value pairs include Widget=widget_name,
Request=request_name, Tab=tab_name, Section=section_name. Also, widgets can use
custom key-value pairs.
IDL Definition
struct RequestArgs{wstring wsName; WStringSeq seqValues; };
Fields
Table 6-11: RequestArgs Fields
Field Use
wsName The argument name
seqValues The arguments value(s)
Widget Data Structures
Livelink UNITE IDL Reference 107

RequestArgsSeq
The RequestArgsSeq data structure is an IDL sequence of RequestArgs data structures
that defines a list of arguments passed in a request. For more information about the
RequestArgs data structure, see RequestArgs, page 106.
IDL Definition
typedef sequence < RequestArgs > RequestArgsSeq;
Widget Data Structures
108 Livelink UNITE Widget Developer's Guide

RequestCookie
The RequestCookie data structure is an IDL structure that contains a cookie from the
members browser received in a request. The cookies are already decoded in the request.
IDL Definition
struct RequestCookie { wstring wsName; wstring wsValue; };
Fields
Table 6-12: Request Cookie Fields
Field Use
wsName The cookie name
wsValue The decoded cookie value
Widget Data Structures
Livelink UNITE IDL Reference 109

RequestCookieSeq
The RequestCookieSeq data structure is an IDL sequence of RequestCookie data
structures received in the request. For more information about the RequestCookie data
structure, see RequestCookie, page 108.
IDL Definition
typedef sequence< RequestCookie > RequestCookieSeq;
Widget Data Structures
110 Livelink UNITE Widget Developer's Guide

Status Data Structures
Status data structures contain widget status information returned to Livelink UNITE. The
status data structures are:
Status
StatusSeq
Widget Data Structures
Livelink UNITE IDL Reference 111

Status
The Status data type is an IDL structure that contains widget status information.
IDL Definition
struct Status
{ wstring wsKey;
long lKind;
wstring wsLabel;
wstring wsString;
long lNumber; };
Fields
Table 6-13: Status Fields
Fields Use
wsKey The unique key name of the status item
lKind Status value kind. Legal values are:
const long kStatus = 0x00000001;
const long kInfo = 0x00000002;
const long kPerformance = 0x00000004;
const long kStatistics = 0x00000008;
const long kDebug = 0x00000010;
const long kOther = 0x00000020;
const long kVersion = 0x00000040;
const long kAll = 0xffffffff;
wsLabel The status item label displayed on Livelink UNITEs status
page
wsString The status value as a string. Specify %1 to insert the value
defined in the lNumber field.
lNumber The numeric value of the status item
Widget Data Structures
112 Livelink UNITE Widget Developer's Guide

StatusSeq
The StatusSeq data structure is an IDL sequence of Status data structures. For more
information about the Status data structures, see Status, page 111.
IDL Definition
typedef sequence< Status > StatusSeq;
Field
Status A structure containing status information
Widget Data Structures
Livelink UNITE IDL Reference 113

General Data Structures
The Livelink UNITE Widget IDL includes a general data structure used to contain String
values.
WStringSeq
The WStringSeq data structure is an IDL sequence of wide string values. Various
Livelink UNITE server and widget data structures use WStringSeq.
IDL Definition
typedef sequence< wstring > WStringSeq;
Widget Exceptions
114 Livelink UNITE Widget Developer's Guide

Widget Exceptions
Livelink UNITE Widget exceptions indicate a kind of error condition encountered during
widget processing.
WidgetError
The WidgetError data type is an IDL exception that widgets return to Livelink UNITE
when an error is encountered. Each WidgetError is accompanied by a String argument,
wsError that indicates the kind of Livelink UNITE error encountered.
IDL Definition
exception WidgetError {wstring wsError;};
Field
wsError Error formatting specification
Livelink UNITE Errors
All Livelink UNITE errors are specified in the following file:
UNITE_home\support\UNITE_language.js.
where UNITE_home is the directory path to the folder where Livelink UNITE program
files are installed, and language indicates the message language. Substitution values
included in Livelink UNITE error messages are indicated by %n, where n is the order of
the substitution value passed to the JavaScript variable. Substitution values follow the
JavaScript variable name and are separated by commas. In addition, the error messages
include the value %A which indicates that the contents of the Page__ContactError
JavaScript variable (if it is defined) is placed at the end of the message. For more
information about the Page__ContactError JavaScript variable, see the Livelink UNITE
Customization Guide.
Widget Exceptions
Livelink UNITE IDL Reference 115

Java Example
In the following sample Java code, a conditional test determines that if a member is
signed in, the widget returns an error indicating that the member does not have
permission to view a requested piece of data:
if ( !spec.bSignedIn )
{
throw new WidgetError( "E__NoPermission" );
}
Members who encounter this error see the following displayed in the widgets
corresponding section:
You do not have permission to perform the requested
operation.
Profile Interface
116 Livelink UNITE Widget Developer's Guide

Profile Interface
The Livelink UNITE profile IDL specification describes the standard interface to Livelink
UNITE profiles. Widgets call profile operations to add, retrieve, or modify information in
a profile. The profile interface operations are:
Copy
Destroy
KeyGet
KeyExists
KeyList
KeyListSort
Modify
NameGet
NKeys
NProperties
PropertyAuthenticate
PropertyExists
PropertyGet
PropertyGetDecrypt
PropertyGetDefaulted
PropertyList
PropertyListNoDefault
SectionGet
Profile Interface
Livelink UNITE IDL Reference 117

Copy
The Copy operation copies the profile into another profile. The operation places the
copied profile contents under the target node specified by a key path.
IDL Syntax
void Copy( in wstring wsKeyPath,
in wstring wsTargetKeyPath,
in Profile oTarget);
Parameters
wsKeyPath The key path of the profile contents to copy
wsTargetKeyPath The key path in the target profile
oTarget The target profile
Profile Interface
118 Livelink UNITE Widget Developer's Guide

Destroy
The Destroy operation destroys a profile.
Important The Destroy operation is reserved for use by Livelink UNITE. Do not call this
operation.
IDL Syntax
void Destroy();
Profile Interface
Livelink UNITE IDL Reference 119

KeyGet
The KeyGet operation returns the value of a nodes default property.
IDL Syntax
wstring KeyGet( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The KeyGet operation returns the property value. An empty string () is returned if the
node does not exist.
Profile Interface
120 Livelink UNITE Widget Developer's Guide

KeyExists
The KeyExists operation verifies that a node exists.
IDL Syntax
boolean KeyExists( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The KeyExists operation returns TRUE if the node exists; FALSE if the node does not
exist.
Profile Interface
Livelink UNITE IDL Reference 121

KeyList
The KeyList operation retrieves the child node names in a node.
IDL Syntax
ProfileValueSeq KeyList( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The KeyList operation returns a list of node names. For more information about the
ProfileValueSeq data structure, see ProfileValueSeq, page 137.
Profile Interface
122 Livelink UNITE Widget Developer's Guide

KeyListSort
The KeyListSort operation retrieves a list of child node names in a node and sorts them
by a property value.
IDL Syntax
ProfileValueSeq KeyListSort( in wstring wsKeyPath,
in wstring wsPropertyName );
Parameters
wsKeyPath The node key path
wsPropertyName The property name used to sort the child nodes
Return Value
The KeyListSort operation returns a list of node names sorted by the specified property
value. For more information about the ProfileValueSeq data structure, see
ProfileValueSeq, page 137.
Profile Interface
Livelink UNITE IDL Reference 123

Modify
The Modify operation performs an operation on a profile. The operation accepts a
sequence of requests specified in the ProfileOperationSeq data structure. Each member
in the sequence is a ProfileOperation data structure that contains an operation name
and any required parameters.
IDL Syntax
void Modify( in ProfileOperationSeq seqOperations);
Parameter
seqOperations A sequence of operations. For more information about the
ProfileOperationSeq data structure, see
ProfileOperationSeq, page 139.
Java Example
The following sample Java widget code calls the rename operation type and passes the
required parameters to change the name of a node from Areas to Location. The node
key path is specified through features in the PageSpec or SectionSpec data structure.
ProfileOperationSeq[] myOperations = new ProfileOperationSeq[ 1 ];

myOperations[ 0 ] = new ProfileOperation(
OperationType.kKeyRename,
+"/Tabs/" + spec.wsTab + "/" + spec.wsSection + "/Areas",
"Locations","", "", "" );
spec.oProfile.Modify( myOperations );
For more information about the ProfileOperation and OperationType data structures,
see ProfileOperation, page 138, and OperationType, page 143.
Profile Interface
124 Livelink UNITE Widget Developer's Guide

NameGet
The NameGet operation retrieves the name of a profile.
IDL Syntax
wstring NameGet();
Return Value
The NameGet operation returns the profile name.
Profile Interface
Livelink UNITE IDL Reference 125

NKeys
The NKeys operation retrieves the number of direct descendent nodes of the member
profile specified by the key path.
IDL Syntax
long NKeys( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The NKeys operation returns an integer representing the number of child nodes in a node.
Profile Interface
126 Livelink UNITE Widget Developer's Guide

NProperties
The NProperties operation retrieves the number of properties in a node.
IDL Syntax
long NProperties( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The NProperties operation returns an integer representing the number of properties in a
node.
Profile Interface
Livelink UNITE IDL Reference 127

PropertyAuthenticate
The PropertyAuthenticate operation compares a value to the one-way encrypted value
stored in a specified property.
IDL Syntax
boolean PropertyAuthenticate( in wstring wsKeyPath,
in wstring wsPropertyName,
in wstring wsValueToAuthenticate);
Parameters
wsKeyPath The node key path
wsPropertyName The property name
wsValueToAuthenticate The value to compare to the property value
Return Value
The PropertyAuthenticate operation returns TRUE if the value equals the property
value; FALSE if the value does not equal the property value or if the node or property
does not exist.
Profile Interface
128 Livelink UNITE Widget Developer's Guide

PropertyExists
The PropertyExists operation verifies that a node contains a specific property.
IDL Syntax
boolean PropertyExists( in wstring wsKeyPath,
in wstring wsPropertyName );
Parameters
wsKeyPath The node key path
wsPropertyName The property name
Return Value
The PropertyExists operation returns TRUE if the property exists; FALSE if the value
does not exist.
Profile Interface
Livelink UNITE IDL Reference 129

PropertyGet
The PropertyGet operation retrieves a property value from a profile.
IDL Syntax
wstring PropertyGet(in wstring wsKeyPath,
in wstring wsPropertyName );
Parameters
wsKeyPath The node key path
wsPropertyName The property name
Return Value
The PropertyGet operation returns the propertys value. If the node or property does
not exist, the operation returns an empty string ().
Profile Interface
130 Livelink UNITE Widget Developer's Guide

PropertyGetDecrypt
The PropertyGetDecrypt operation retrieves the encrypted value of a node property
and returns it in decrypted form.
IDL Syntax
wstring PropertyGetDecrypt(in wstring wsKeyPath,
in wstring wsPropertyName,
in wstring wsKey );
Parameters
wsKeyPath The node key path
wsPropertyName The property name
wsKey The value used to encrypt the data
Return Value
The PropertyGetDecrypt operation returns an encrypted property value in decrypted
form. If the node or property does not exist, an empty string is returned.
Profile Interface
Livelink UNITE IDL Reference 131

PropertyGetDefaulted
The PropertyGetDefaulted operation retrieves the value of a node property. If the node
or property does not exist, a default value is returned.
IDL Syntax
wstring PropertyGetDefaulted(in wstring wsKeyPath,
in wstring wsPropertyName,
in wstring wsDftPropertyValue );
Parameters
wsKeyPath The node key path
wsPropertyName The property name
wsDftPropertyValue The default value returned if the node or property name does
not exist
Return Value
The PropertyGetDefaulted operation returns the propertys value. If the node or
property does not exist in the profile, the operation returns the default string.
Profile Interface
132 Livelink UNITE Widget Developer's Guide

PropertyList
The PropertyList operation retrieves all property names and values of the node
specified by a key path.
IDL Syntax
ProfileValueSeq PropertyList( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The PropertyList operation returns a list of the property names and values in a node.
For more information about the ProfileValueSeq data structure, see ProfileValueSeq,
page 137.
Profile Interface
Livelink UNITE IDL Reference 133

PropertyListNoDefault
The PropertyListNoDefault operation returns all property names and values in a node
except the default property and value.
IDL Syntax
ProfileValueSeq PropertyListNoDefault( in wstring wsKeyPath );
Parameter
wsKeyPath The node key path
Return Value
The PropertyListNoDefault operation returns a list of all property names and values
except the default property name and value. For more information about the
ProfileValueSeq data structure, see ProfileValueSeq, page 137.
Profile Interface
134 Livelink UNITE Widget Developer's Guide

SectionGet
The SectionGet operation returns a complete section definition. A section definition
contains all the section node property names plus a list of all child nodes and their
properties and values.
IDL Syntax
ProfileSection SectionGet( in wstring wsKeyPath );
Parameter
wsKeyPath The section node key path
Return Value
The SectionGet operation returns a list of the properties and values. For more
information about the ProfileSection data structure, see ProfileSection, page 142.
Profile Data Structures
Livelink UNITE IDL Reference 135

Profile Data Structures
The Livelink UNITE profile IDL specification defines a number of data structures. Data
structures are used to pass information between the Livelink UNITE extension and
widgets. The profile data structures include:
ProfileValue
ProfileValueSeq
Profile Operation
ProfileOperationSeq
ProfileChild
ProfileChildSeq
ProfileSection
OperationType
Profile Data Structures
136 Livelink UNITE Widget Developer's Guide

ProfileValue
The ProfileValue data structure is an IDL structure that defines a node property name
and value.
IDL Definition
struct ProfileValue { wstring wsName;
wstring wsValue; };
Fields
Table 6-14: ProfileValue Fields
Name Use
wsName The property name
wsValue The property value
Profile Data Structures
Livelink UNITE IDL Reference 137

ProfileValueSeq
The ProfileValueSeq data structure is an IDL sequence of ProfileValue data
structures. For more information about ProfileValue data structures, see
ProfileValue, page 136.
IDL Definition
typedef sequence< ProfileValue > ProfileValueSeq;
Profile Data Structures
138 Livelink UNITE Widget Developer's Guide

ProfileOperation
The ProfileOperation data structure is an IDL structure that contains fields that specify
the arguments for a profile operation request. ProfileOperation data structures are
passed to the Modify operation through the ProfileOperationSeq data structure. For
more information about the Modify operation and the ProfileOperationSeq data
structure, see Modify, page 123 and ProfileOperationSeq, page 139.
IDL Syntax
struct ProfileOperation {long lOperation;
wstring wsParam1;
wstring wsParam2;
wstring wsParam3;
wstring wsParam4;
wstring wsParam5};
Fields
Table 6-15: ProfileOperation Fields
Name Use
lOperation A value from the OperationType enumeration that indicates what operation
to perform on a profile. For more information about the OperationType
enumeration, see OperationType, page 143.
wsParam1 The first parameter required by the operation type
wsParam2 The second parameter required by the operation type
wsParam3 The third parameter required by the operation type
wsParam4 The fourth parameter required by the operation type
wsParam5 The fifth parameter required by the operation type
Note A value or null string () must be specified in each parameter field. If a
value is specified in a parameter field not used by an operation, the value is
ignored.
Profile Data Structures
Livelink UNITE IDL Reference 139

ProfileOperationSeq
The ProfileOperationSeq is an IDL sequence of ProfileOperation data structures.
IDL Definition
typedef sequence< ProfileOperation > ProfileOperationSeq;
Field
ProfileOperation A data structure containing profile operation arguments. For
more information about the ProfileOperation data structure,
see ProfileOperation, page 138.
Profile Data Structures
140 Livelink UNITE Widget Developer's Guide

ProfileChild
The ProfileChild data structure is an IDL structure that defines a child node property
name and its value.
IDL Definition:
struct ProfileChild { wstring wsName;
ProfileValueSeq seqProperties; };
Fields
Table 6-16: ProfileValue Fields
Name Use
wsName The child node name
seqProperties A list of properties and values in the child node. For more
information about the ProfileValueSeq data structure, see
ProfileValueSeq, page 137.
Profile Data Structures
Livelink UNITE IDL Reference 141

ProfileChildSeq
The ProfileChildSeq data structure is an IDL sequence of ProfileChild data
structures. For more information about the ProfileChild data structure, see
ProfileChild, page 140.
IDL Definition
typedef sequence< ProfileChild > ProfileChildSeq;
Profile Data Structures
142 Livelink UNITE Widget Developer's Guide

ProfileSection
The ProfileSection data structure is an IDL structure that defines a complete node
section. A node section contains:
Node properties and values
Child node properties and values
IDL Definition
struct ProfileSection { ProfileValueSeq seqProperties;
ProfileChildSeq seqChildren; };
Fields
Table 6-17: ProfileValue Fields
Name Use
seqProperties A list of properties and values in the node. For more information
about the ProfileValueSeq data structure, see ProfileValueSeq,
page 137.
seqChildren A list of child nodes and their property names and values. For more
information about the ProfileChildSeq data structure, see
ProfileChildSeq, page 141.
Profile Data Structures
Livelink UNITE IDL Reference 143

OperationType
The OperationType is an IDL enumeration that indicates the type of operation to
perform on a profile. A OperationType value is specified as an argument in the
ProfileOperation data structure. The Modify operation performs the profile operation
based on the arguments in a ProfileOperation data structure. For more information
about the ProfileOperation data structure, see ProfileOperation, page 138.
IDL Definition
enum OperationType {kKeySet,
kKeyRemove,
kKeyRename,
kPropertySet,
kPropertySetSecure,
kPropertySetEncrypt,
kPropertyRemove,
kMove }
Values
Table 6-18: ProfileOperationType Values
Operation name Specifies
kKeySet An operation that updates a nodes default or unnamed property
or creates the node if it does not exist. The operation accepts two
parameters:
keyPath, the node key path of the node to update or create
keyValue, the nodes default property value
kKeyRemove An operation that removes a node and all descendant nodes from
the profile. The operation accepts the parameter keyPath, the
node key path of the node to remove.
kKeyRename An operation that renames a node. The operation accepts two
parameters:
keyPath, the node key path of the node to update or create
newName, the new node name
kPropertySet An operation that adds a property name and value to a node. The
operation accepts three parameters:
keyPath, the node key path
propertyName, the property name
propertyValue, the new property value
Note: Root node properties are reserved for use by Livelink
UNITE. Do not create properties in the root node.
Profile Data Structures
144 Livelink UNITE Widget Developer's Guide

Table 6-18: ProfileOperationType Values
Operation name Specifies
kPropertySetSecure An operation that sets a node property and provides one-way
encryption for the property value. The operation accepts three
parameters:
keyPath, the node key path
propertyName, the property name
propertyValueToEncrypt, the property value to be encrypted
kPropertySetEncrypt An operation that sets a node property and provides two-way
encryption for the property value. The operation accepts three
parameters:
keyPath, the node key path
propertyName, the property name
propertyValueToEncrypt, the property value to be encrypted
encryptKey, the values used to encrypt the property
For more information about retrieving the property value in its
decrypted form, see PropertyGetDecrypt, page 130.
kPropertyRemove An operation that removes a property and value from a node.
The default property cannot be removed; if the default property
is specified, the value is reset to blank (). The operation accepts
two arguments:
keyPath, the node key path
propertyName, the property removed
kMove An operation that moves a nodes child nodes to a target node.
The operation accepts two parameters:
keyPath, the node key path of the node that contains child nodes
targetKeyPath, the node key path where the child nodes are
moved
Profile Exceptions
Livelink UNITE IDL Reference 145

Profile Exceptions
The profile IDL specification defines one exception thrown by profile operations. It also
contains exceptions encountered by reserved Livelink UNITE password operations.
A widget may encounter other problems while performing profile operations. If this
occurs, the widget must generate an appropriate widget exception. For more information
about widget exceptions, see Widget Exceptions, page 114.
ProfileCannotRemoveRoot
If a profile operation encounters an error while removing a profile root node, it returns
the ProfileCannotRemoveRoot exception.
System Log Writer Interface
146 Livelink UNITE Widget Developer's Guide

System Log Writer Interface
The Livelink UNITE System Log Writer IDL specification describes the standard interface
to the Livelink UNITE system log writer object. Widgets call system log writer operations
to write messages to the Livelink UNITE log file.
The system log writer interface operations are:
Append
AppendAsSender
System Log Writer IDL File
The Livelink UNITE System Log Writer IDL file must be compiled in your development
environment. This translates the Livelink UNITE System Log Writer IDL operations into
constructs of the local programming language. Livelink UNITEs System Log Writer IDL
file is included in the Livelink UNITE Widget Development Kit in the following location:
Livelink_UNITE_WDK\idl\LLSysLogWriter.idl
where Livelink_UNITE_WDK is the directory name where you installed the Livelink
UNITE Widget Development Kit.
System Log Writer Interface
Livelink UNITE IDL Reference 147

Append
The Append operation adds a message to Livelink UNITEs log file.
oneway void Append( in wstring wsLine );
Parameter
wsLine The message added to the log file
System Log Writer Interface
148 Livelink UNITE Widget Developer's Guide

AppendAsSender
The AppendAsSender operation adds a widget name and message to the Livelink UNITE
log file.
oneway void AppendAsSender( in wstring wsSender, in wstring wsLine );
Parameters
wsSender A string that identifies the widget sending the message
wsLine A message added to the log file


149

Chapter Seven
Required JavaScript Variables
Livelink UNITE requires each widget to set three JavaScript functions that define
properties used to identify the widget throughout the system.
Widget Presentation and Administration, page 150
Widget Name, 151
Administration Page Description, page 152

Widget Presentation and Administration
150 Livelink UNITE Widget Developer's Guide

Widget Presentation and Administration
Each widget defines where its sections are presented on a tab and whether it has an
Administration page. You specify a widgets presentation and administration preferences
in the WidgetInfo variable:
widgetname__WidgetInfo = properties
where widgetname is the widgets name and properties are a string of presentation and
administration properties applied to your widget.
Table 7-1: WidgetInfo Properties
Property Result
D Creates a link from the Livelink UNITE Section Administration page to the
widgets Administration page. If your widget uses an Administration page,
the function in your widget code that creates it must be named Admin.
A If domains are not enabled, creates a link from the Livelink UNITE Section
Administration page to the widgets Administration page. If domains are
enabled, the link appears under Global Section Administration.
If your widget uses an Administration page, the function in your widget code
that creates it must be named Admin.
T Members can add the widgets section to thin columns on the left and right
sides of a tab.
W Members can add the widgets section to the wide column in the center of a
tab.
For example, imagine a widget named Sports that has an administration page and is
available only in the center, wide column of a tab. The developer specifies the following
WidgetInfo setting:
Sports_WidgetInfo = AW
WidgetInfo properties can be specified in any order and do not require spaces, commas,
or any other separator. The WidgetInfo variable is specified in a widgets JavaScript file.
For more information about the widgets JavaScript file, see the Livelink UNITE
Customization Guide.
Widget Name
Required JavaScript Variables 151

Widget Name
A widgets name appears on page headers and elsewhere in Livelink UNITEs interface
by references to the WidgetName variable:
widgetname__WidgetName = name
where widgetname is the widgets name and name is the widget name displayed in
Livelink UNITEs interface. For example, the Weather widgets WidgetName variable is
set as follows:
Weather_WidgetName = Weather
The WidgetName variable is specified in a widget's language file. For more information
about widget language files, see the Livelink UNITE Customization Guide.
Administration Page Description
152 Livelink UNITE Widget Developer's Guide

Administration Page Description
Livelink UNITE provides a brief description about each widget available to a member on
the About Livelink UNITE page. Each widget specifies its description in the
WidgetAbout variable:
widgetname__WidgetAbout = description
where widgetname is the widgets name and description is the widget description
displayed on the About Livelink UNITE page. For example, the Weather widgets
WidgetAbout variable is set as follows:
Weather_WidgetName = 'Watch the weather conditions in cities
of interest around the world.'
The WidgetAbout variable is specified in a widget's language file. For more information
about widget language files, see the Livelink UNITE Customization Guide.

Figure 7-1: Weather Widget Description Taken From the About Livelink UNITE page






153


Index
_
__WidgetAbout, 152
__WidgetInfo, 150
__WidgetName, 151
A
accessing member profiles, 27
administration
__WidgetAbout variable, 152
__WidgetInfo variable, 150
administration pages, 23
Append operation, 147
AppendAsSender operation, 148
B
building widgets, 16
C
C++
use in custom widgets, 50
Common Object Request Broker Architecture
(CORBA)
more information, 15
overview, 14
configuration pages, 22
Conventions
typographical, iii
Copy operation, 117
creating widgets, 16
D
data structures
OperationType, 143
page rendering, 92
PageInfo, 93
PageInfoButton, 96
PageInfoButtonSeq, 97
PageInfoCookie, 98
PageInfoCookieSeq, 99
PageInfoCookieStatus, 100
PageInfoHeaderType, 104
PageSpec, 101
profile, 135
ProfileChild, 140
ProfileChildSeq, 141
ProfileOperation, 138
ProfileOperationSeq, 139
ProfileSection, 142
ProfileValue, 136
ProfileValueSeq, 137
request, 105
RequestArgs, 106
RequestArgsSeq, 107
RequestCookie, 108
RequestCookieSeq, 109
section rendering, 85
SectionInfo, 86
SectionSize, 91
SectionSpec, 88
status, 110
Status, 111
StatusSeq, 112
widget, 84
WStringSeq, 113
Destroy operation, 80
Destroy operation, 118
detach view, 22
developing widgets, 16

154 Livelink UNITE Widget Developer's Guide
E
encryption
setting profile values, 134
error messages, 114
exceptions
profiles, 145
widgets, 114
F
front page, 4
Front Page widget, 4
full-page view, 22
I
Interface Definition Language (IDL)
overview, 14
widget IDL file, 71
Interoperable Object Reference (IOR) file, 8
J
Java
prerequisite knowledge, 13
sample widget, 37
Java Development Kit
supported version, 13
JavaScript variables
__WidgetAbout, 152
__WidgetInfo, 150
__WidgetName, 151
error messages, 114
K
KeyExists operation, 120
KeyGet operation, 119
KeyList operation, 121
KeyListSort operation, 122
L
Livelink UNITE
architecture, 2
components, 2
extension, 3
Front Page widget, 4
IOR file, 8
Java sample widget, 37
log files, 29
Naming service object, 8
processing requests, 10
profiles, 25
signing in, 10
system log, 9
Widget Development Kit, 1
Livelink UNITE extension, 3
Livelink UNITE Widget Development Kit, 1
log settings, 29
M
member profile
structure, 26
member profiles, 7, 26
retrieving, 27
Modify operation, 123
modifying
profiles, 123
My Profile, 7
N
NameGet operation, 124
Naming service object, 8
NKeys operation, 125
node key path, 26
Notify operation, 77
NProperties operation, 126
O
Object Management Group (OMG)
overview, 14
web site, 15
Object Request Broker (ORB), 15
objects
accessing the system log object, 30
member profile, 26
Naming service, 8
system log, 9
system profile, 27
widgets, 71
operations
Append, 147

Index 155
AppendAsSender, 148
Copy, 117
Destroy, 80, 118
KeyExists, 120
KeyGet, 119
KeyList, 121
KeyListSort, 122
Modify, 123
NameGet, 124
NKeys, 125
Notify, 77
NProperties, 126
Ping, 79
PropertyAuthenticate, 127
PropertyExists, 128
PropertyGet, 129
PropertyGetDecrypt, 130
PropertyGetDefaulted, 131
PropertyList, 132
PropertyListNoDefault, 133
RenderPage, 74
RenderProgressivePage, 82
RenderRawPage, 81
RenderSection, 73
RenderSectionCallback, 83
SectionGet, 134
StatusClear, 76
StatusGet, 75
OperationType data structure, 143
P
page rendering, 22
PageInfo data structure, 93
PageInfoButton data structure, 96
PageInfoButtonSeq data structure, 97
PageInfoCookie data structure, 98
PageInfoCookieSeq data structure, 99
PageInfoCookieStatus data structure, 100
PageInfoHeaderType data structure, 104
pages
administration, 23
configuration, 22
data structures, 92
detach view, 22
online help, 23
PageInfo data structure, 93
PageInfoButton data structure, 96
PageInfoButtonSeq data structure, 97
PageInfoCookie data structure, 98
PageInfoCookieSeq data structure, 99
PageInfoCookieStatus data structure, 100
PageInfoHeaderType data structure, 104
PageSpec data structure, 101
RenderPage, 74
PageSpec data structure, 101
Ping operation, 79
prerequisite knowledge, 13
processing requests, 10
Profile interface, 116
Profile Manager, 5
ProfileChild data structure, 140
ProfileChildSeq data structure, 141
ProfileOperation data structure, 138
ProfileOperationSeq data structure, 139
profiles, 5
architecture, 25
Copy operation, 117
data structures, 135
Destroy operation, 118
exceptions, 145
KeyExists operation, 120
KeyGet operation, 119
KeyList operation, 121
KeyListSort operation, 122
member, 7
Modify operation, 123
modifying, 123
My Profile, 7
NameGet operation, 124
NKeys operation, 125
node key path, 26
NProperties operation, 126
OperationType data structure, 143
overview, 25
ProfileChild data structure, 140
ProfileChildSeq data structure, 141
ProfileOperation data structure, 138
ProfileOperationSeq data structure, 139
ProfileSection data structure, 142
ProfileValue data structure, 136
ProfileValueSeq data structure, 137
PropertyAuthenticate operation, 127
PropertyExists operation, 128
PropertyGet operation, 129
PropertyGetDecrypt operation, 130
PropertyGetDefaulted operation, 131
PropertyList operation, 132

156 Livelink UNITE Widget Developer's Guide
PropertyListNoDefault operation, 133
SectionGet operation, 134
Site, 6
System, 6
viewing contents, 28
ProfileSection data structure, 142
ProfileValue data structure, 136
ProfileValueSeq data structure, 137
PropertyAuthenticate operation, 127
PropertyExists operation, 128
PropertyGet operation, 129
PropertyGetDecrypt operation, 130
PropertyGetDefaulted operation, 131
PropertyList operation, 132
PropertyListNoDefault operation, 133
R
registering widgets, 17
RenderPage
data structures, 92
RenderPage operation, 74
RenderProgressivePage operation, 82
RenderRawPage operation, 81
RenderSection
data structures, 85
RenderSection operation, 73
RenderSectionCallback operation, 83
request handling, 11
RequestArgs data structure, 106
RequestArgsSeq data structure, 107
RequestCookie data structure, 108
RequestCookieSeq data structure, 109
requests
data structures, 105
retrieving member profiles, 27
S
sample widgets, 35
section rendering, 21
SectionGet operation, 134
SectionInfo data structure, 86
sections
data structures, 85
detached, 22
RenderSection, 73
SectionInfo data structure, 86
SectionSize data structure, 91
SectionSpec data structure, 88
SectionSize data structure, 91
SectionSpec data structure, 88
signing in, 10
Site profile, 6
status
data structures, 110
Status data structure, 111
StatusClear, 76
StatusGet, 75
StatusSeq data structure, 112
Status data structure, 111
StatusClear operation, 76
StatusGet operation, 75
StatusSeq data structure, 112
system architecture diagram, 2
system log, 9
Append operation, 147
AppendAsSender operation, 148
settings, 30
system log object, 9
accessing, 29
System Log Writer, 29
system profile, 27
System profile, 6
V
viewing profile contents, 28
W
Web server integration, 3
Widget interface, 72
Widget_SectionCallback interface, 83
WidgetError, 114
widgets
About box, 152
administration pages, 23
administrative settings, 150, 151, 152
building, 16
configuration pages, 22
data structures, 84
defined, 3
detach view, 22
error messages, 114
exceptions, 114
Front Page, 4
full-page view, 22

Index 157
how requests are processed, 11
IDL, 71
Java sample, 37
member profiles, 26
name variable, 151
online help, 23
overview, 3, 20
page rendering, 22
profile interface, 116
property variables, 149
registering, 17
samples, 35
section rendering, 21
system profile, 27
Widget interface, 72
Widget_SectionCallback interface, 83
WStringSeq data structure, 113


158 Livelink UNITE Widget Developer's Guide