xpages jumpstart - engageengage.ug/.../$file/blugxpagesjumpstart.pdf · xpages jumpstart paul t....

XPages Jumpstart

Paul T. Calhoun Development Services Manager

GBS [email protected]

Obligatory Introduction Paul T. Calhoun

Development Services Manager GBS

Have attained Notes/Domino 6, 7, and 8

PCLI and PCLP certification Currently build Domino, Web, Java, XML, and XPage

applications for customers using Domino, Portlet Factory, and WebSphere Application Server

Co-author of the IBM Redbook “XML Powered by Domino,” and have developed several online XML, Java, and XPages programming courses

Have written articles for both “THE VIEW” and “The Sphere” technical publications

2

What We Will Cover … What Are XPages? Learning XPages Roadmap

Understanding Data Sources Learning Controls

Implementing Controls

Code Language Options Wrap-Up

3

Version 8.5.2 All of the material in this presentation is based

upon Notes/Domino version 8.5.2fp1

– This is the version you should be starting with at this point

–  If you have 8.5.0 then you should upgrade as soon as possible

4

What Are XPages? XPages are a new design element available in

Domino Designer 8.5

XPages are based on Sun’s Java Server Faces (JSF) technology

– This technology lets developers easily create Web 2.0-enabled Web pages for Web browsers

•  Domino/Notes 8.5.0 – Web browser clients only

•  Domino/Notes 8.5.1 – Web browser clients and Notes clients*

5

*XPages rendered in the Notes client are rendered in an internal browser and not the Notes client environment

XPages Use Domino Data Sources An XPage contains a set of controls used to display

Domino data – Fields from Domino documents – Complete or partial view definitions

XPages provide complete separation of the data from

the user interface Domino Documents and Views are used only as a data source and do not control the user interface

•  This allows for the easy development of a Web page that can combine Domino data from different sources

–  Multiple views –  A View and a Document on the same page

6

XPages Are Styled with CSS and Themes

Applications are styled using a combination of Cascading Style Sheets (CSS) and Themes

– CSS are used as the primary styling technique Themes are another new styling design element in

Release 8.5

– Themes allow an application to change its appearance by specifying a different theme

•  At the application level •  At the server level

7

XPage Architecture Under the covers, an XPage source is entirely

XML syntax

– XPages are written in JSP tag syntax – XPage code is then compiled into Java source

code and executed by the Domino Servers XPage runtime

•  The XPage runtime is part of the Domino server’s HTTP stack

8

XPage Architecture

Domino Server

.NSF

Domino HTTP Task

XSP Engine

Web Browser Client IE

FireFox Chrome XPiNC

Available Design Features Controls palette

– Core controls – Container controls – Custom controls

AJAX support – Type ahead – Partial page refresh

Localization options CSS Themes

10

Available Design Features (cont.) Coding support

– JavaScript •  Client side •  Server side •  Dojo libraries

– Expression Language (EL) – @Functions

•  Similar syntax to Notes/Domino @Functions – Direct access to Java libraries

•  Standard SDK libraries •  Custom coded libraries

11

XPage Design Environment

12

Outline View

Editor View

Properties, Events, and Problems

Controls and Data palettes

Demo — XPage Design Environment

13





14

Learning XPages Learning XPages is journey, not a destination

– You will not walk out of this room knowing everything you need to know about developing XPages!

You need to plan/budget at least three months for this adventure –  Longer if you have a full time job that does not

include XPage development Don’t believe the marketing hype!

–  Learning XPages is not necessarily: •  Easy •  Intuitive •  Quick

15

If You Are a Domino Developer … Then XPages are something you have never experienced before

–  Even if you had done Web page development

It requires a new way of thinking about applications XPage solutions are browser-based

–  Even if running in the Notes client

If you are unfamiliar with any of the following then you need to spend some time learning them first! In this order! –  XML –  XHTML –  CSS –  JavaScript –  Java

16

Developer: Paul, this XPage doesn’t work. Paul: The XPage is fine, it’s your XML, XHTML, CSS, JavaScript, Java syntax that is not working.

If You Are a Domino Web Developer … Then I’m assuming* that you are familiar with all of

the following: – XML – XHTML – CSS – JavaScript – Java

17 * We all know what that means.

If You Are a Domino Web Developer … Even with that knowledge, XPages are compiled into

Java at runtime – So it is not the same as developing Web pages

using the previous skills and “seeing what it looks like”

What you see in the designer is not necessarily what you are going to see rendered in the browser

HTML ID attributes behave differently from designer to run-time

18

If You Are a Java/JEE Developer … Then yes, you too have to know:

–  XML –  XHTML –  CSS –  JavaScript

But you also need to know Notes/Domino –  This could be your weakest area –  All of the data comes out of Domino, so you need to

know the Domino back-end API

You are not necessarily going to be able to “code around the problem”

Java code should be the last tool you reach for in your toolbox when creating XPages

19

How Most Developers Start the Process Choose a corporate-wide, high-profile, mission-critical application that is due in

production in one month

Create a new Domino application (.nsf)

Create a new XPage –  What’s a data source?

Start adding controls

–  What’s this data binding thing? –  Do I add text in the editor or use Label controls?

Start adding code to the controls

–  What’s the difference between client and server-side JavaScript? –  When can I use the @Functions? –  What is the expression language?

Why does my CSS work in designer and not in the browser?

Developing XPages Sucks !!!!

20

A Better Approach Choose an application that is smaller in scale

–  Duplication of an existing department or workgroup application –  Relatively small target/test audience of preferably friendly folks

Understand what data sources are available to XPages

–  Currently only Domino elements •  Documents •  Views

So unless you are creating an XPage with static content, then you have to have a data source

–  An existing application (.nsf) with form and view designs that can be used

–  A new application (.nsf) where the first elements defined are the form(s) and view(s) to be used as the data sources

21

Next … Learn the different types of controls

–  In Domino form development, we are used to adding “fields” with different properties to the form

–  In XPage development, we have “controls,” some of which map to the different Domino “field” types

•  Editable –  Text –  Dialog List –  Combo Box –  Etc.

•  Computed •  Computed When Composed •  Computed for Display

22

More on Controls … Controls have common properties, specific properties, and

events

There are several categories of controls –  Edit controls

•  Edit Box, Multiline Edit Box, Date Time Picker, Rich Text –  Selection controls

•  Combo Box, List Box, Check Box, Radio Button –  Action controls

•  Button, Link, File Upload, File Download –  Display controls

•  Label, Image, Computed –  Container controls

•  Data Table, Include Page, Panel, Repeat, Section, Tabbed Panel

•  Table, View

23

Some Controls Will Be Used More Often

As in Domino form development, some controls will be used more often than others

– Concentrate on the following: •  View •  Edit box •  Label •  Computed •  Button •  Repeat

– Radio buttons and check boxes require some special consideration (more on this later)

24

Get Familiar with the Language Options

Coding languages that is :

– @Functions – JavaScript

•  Client-side •  Server-Side

– Java

25

Did you notice that LotusScript was not an option? No, it’s not ever going to be an option. *

So does that mean you have to learn JavaScript? Yes, that is exactly what that means!

Back to the Roadmap … Plan the “look and feel” from the beginning of the

development process, not as the last thing that’s added

–  Create/incorporate existing CSS resources at the beginning of the development

–  Understand that XPage CSS is heavily class-based and will not work with ID attributes well

Domino Developers tend to format things as they go –  This should be centered, that should be bold … and

purple

Don’t add any manual formatting –  Always allow formatting to flow from the theme or CSS

classes

26

Know Your Browser Target Which browsers are you targeting? Test with multiple browsers

–  IE – Firefox – Chrome – XPiNC

This has the potential to affect your coding

– Whether to use Dojo or not – Whether to add browser testing to your code

27

Learn Fundamentals First Put off reviewing advanced techniques until you have learned the

fundamentals There are a lot of …

–  Really cool –  Bleeding edge –  Fancy –  Advanced –  Knock your socks off –  … XPage examples and techniques out in the cloud

But most of them assume some base/core XPage knowledge So spend time grounding yourself in the base/core knowledge and

then start exploring these great resources –  I will provide a list of really great resources at the end

28

Roadmap Recap To learn XPages without going crazy:

– Start with a small manageable project •  This could even be a personal, non-production project

– Know where the data comes from •  Currently all XPage data comes from Domino documents

and views –  Can be in the same application (.nsf) or a referenced

application

–  Learn the controls –  Learn the coding language options – Think about the “look and feel” at the beginning

of the design, not at the end •  Use existing CSS resources

29

Roadmap Recap (cont.) To learn XPages without going crazy: (cont.)

– Gradually start looking at other peoples’ examples – XPages have been out for a while

•  Chances are someone has already solved all or part of the problem you are having

•  Monitor the blogs, wikis, and discussion forums –  Resources at end of slides

If you learn something really cool that you haven't seen before then share it with the community! – Even if you don’t have your own personal Web

site/blog, there are several places to share your solutions

•  openNTF •  developerWorks wikis

30

What We’ll Cover … What Are XPages? Learning XPages Roadmap




31

XPage Data Sources Currently the only available data sources for XPages are:

–  Domino •  Documents

–  Controls in the XPage are ”bound” to the fields defined in the documents form design

•  Views –  Columns defined in the view are available in the View control on the

Xpage

What about other data sources?

–  Relational data •  Not supported as a data source (yet) but available via JDBC

–  XML •  XML data can be parsed/transformed and displayed

–  I have a session on this tomorrow

32

Adding Data Sources Data sources can be added during XPage creation XPage names must be valid Java Identifiers

– Can not contain spaces – Must begin with a letter or an underscore

Only one data source can be added when creating an XPage

To add a data source check the “Add data source to the page” checkbox

33 31

Adding Data Sources

Adding a View Data Source Choose “Domino View” as the data source Select either the Current application or any selectable

application from your workspace Select the View to act as the data source from the

drop-down list Accept the default name

or provide a more meaningful one

There can be multiple view data sources, so avoid names like “view1” and “view2”

35 32

Adding a Document Data Source Choose “Domino Document” as the Data source

Select either the Current application or any selectable application from your workspace

Select the Form to act as the data source from the drop down list

The default name for a new Document data source is “dominoDocument1” –  If adding the data source

after the XPage is created, the default name is “document1”

–  It is best to be consistent in the naming used

36 33

Add Data Sources After Creating XPage

View and document data sources can be added/edited after the XPage is created

– On the Properties tab of the XPage, choose the “Data” category

– Click the “Add” button – Choose either:

•  Domino View •  Domino Document

37

Adding a View Data Source Select either the Current application or any

selectable application from your workspace

Select the view to act as the data source from the drop-down list

– Unlike when adding a view data source when the XPage is created, the default data source name is “view1”

The data source name becomes a global variable available programmatically to the XPage

38

Adding a View Data Source

Adding a Document Data Source Select either the Current application or any

selectable application from your workspace Select the Form to act as the data source from the

drop-down list – The default Document data source name is “document1”

•  This is not the same as when the XPage is created Default action can be:

– Create document – Edit document – Open document

40 36

Adding a Document Data Source

41

There Can Be Multiple Data Sources An XPage can have both document and view data

sources as well as having several of the same type of data sources

– “N” number of view data sources – “N” number of document data sources

42

Data Sources Contained in External .NSFs

XPage data sources do not have to be from the same application (.nsf)

An XPage application can act as an aggregator of data from several different applications

43

SalesTotals.nsf

Sales.nsf SalesForce.nsf

Data Sources Are Available on the Data Palette

44

Data Palette

Added Data Sources Are Available from the Data Palette (cont.)

45

Data Palette

Data Palette Elements Elements from the Data palette can be dragged

onto the editor to create controls

– More on this in the Implementing Controls section

46

Domino Data Sources

47




Making It Look Pretty Code Language Options

Custom Controls

Wrap-Up 48

Controls-The XPage Building Blocks Controls provide the XPage building blocks for displaying and

editing data Controls are categorized on the palette by:

–  Core –  Container

Core control category includes: –  Edit controls –  Selection controls –  Action controls –  Display controls

Container control category includes:

–  Controls for containing and repeating elements

49

Common Properties Many of the controls (input controls especially)

have some common properties

– These are properties that are the same for each type of control

50 45

Edit Controls Edit Box

– Provides an input field to enter a single line of data

– Data Type •  String •  Mask •  Number •  Date/Time

51 49

Edit Box Edit Boxes are also used to display numerical data

– Decimal – Currency – Percent – Custom

52

Edit Controls Multiline Edit Box

– Provides an input field to enter multiple lines of data

53

Edit Controls (cont.) Date Time Picker

– Provides the exact same Dojo calendar and time selection pop-up controls and display options as are available for an Edit Box control with the Date/Time display type specified

54

55

Edit Controls (cont.) Rich Text

–  A CKEditor rich text editor

–  Three Types available •  Slim •  Medium (default) •  Large

Versions prior to 8.5.2 used the Dojo Rich Text Editor

Reverting to the Old Dojo Rich Text Editor In the Dojo section of the Rich Text controls Properties

tab –  Type the following into the Dojo type field

•  ibm.xsp.widget.layout.RichText

56

Selection Controls Combo Box and List Box

– Have the same common properties – List Boxes include option to allow multiple

selections

57 54

Selection Control Values Values for the Combo and List Box controls are

added via the Values Category on the Properties Tab

–  If entries in the Value column are omitted then the label becomes the value

– Values can be: •  Static •  By Formula •  Imported

58 55

Importing Selection Control Values Values can be copied from the Domino form

design

59

Easier Entry of Static Values It is easier to type static values into the Import List

dialog than it is to type them in one value at time in the Values tab

60

61

Selection Controls Radio Buttons and Check Boxes

–  The Radio Button and Check Box controls are for individual elements

•  So really these are good for ... nothing What you need is Radio Button and Check Box group

controls –  Native Palette controls introduced in version 8.5.2 –  Prior to that you had to implement them manually in the

source view

62

Radio Buttons and Check Boxes in 8.5.1/0 Implementing these group controls requires the following

procedure –  Add a Combo Box control to the XPage –  Add the Values

63

Radio Buttons and Check Boxes in 8.5.1/0 Switch to the Source tab of the XPage Find the source of the combo box control

64

Radio Buttons and Check Boxes in 8.5.1/0 Manually edit the source to add the correct Tag

–  checkBoxGroup –  radioGroup

61

65

Radio Buttons and Check Boxes in 8.5.1/0 Once the source is edited, Radio Button and Check

Box groups will show up in the Design tab with the following format

66

Radio Buttons and Check Boxes in 8.5.1/0 Once the source is changed, then edits to the group’s

properties will need to be made in the source view The default direction of the elements is horizontally

side-by-side For a vertical layout, manually add layout=“pageDirection”

Selection Controls In 8.5.2, Radio Button and Check Box group are now core

controls –  Similar to the List Box and Combo Box Control –  Properties are now available via the Properties Tab

67

Action Controls Button

– There are three button types: •  Button

– Generic button that requires adding code to the onClick event

•  Submit –  Automatically submits the page

•  Cancel –  Automatically cancels the page

68 64

Action Controls (cont.) Link

– A Link control can: •  Open a URL •  Open another XPage •  Navigate to another input control on the current

XPage

69 65

Action Controls (cont.) File Upload and File Download

– Provides ability to upload/download file on an XPage

70

Display Controls Label

– Used to display static (or computed) text on an XPage

71

Display Controls (cont.) Label

– Advantages of using a label control vs. static text on the page

•  The text can be computed •  The height and width can be controlled •  The xspTextLabel class is automatically added and

can be formatted using a CSS style sheet •  The label control supports both client and server-side

events •  A target control (typically an Edit control) can be

specified for focus when the label is clicked

72 68

Display Controls (cont.)

73 68

Display Controls (cont.) Image

–  Image controls display graphic images on the XPage

–  Images must be Image resources added to the .nsf

74

Display Controls (cont.) Computed

– The Computed Field tab in the Properties view includes a “Content type” property

•  Choose “Text” or “HTML” as the content type

75

Display Controls (cont.) Computed

– The Value tab in the Properties view is where the computational logic for the computed field goes

•  Code for computed fields will always be Server-Side JavaScript (SSJS)

76

Container Controls View

– A data table that maps to a Domino view data source that displays its contents in rows and columns of data

•  The data source can be associated to the XPage or the view control

– Which one will depend upon what you are trying to accomplish

77

Container Controls (cont.) Data Table

– Data tables are similar to views in that they can display data from a data repository

– They are different from views in that they display data in controls, and users can edit data in a data table if it is displayed in a control that accepts input

Several data table examples will be reviewed

78

Container Controls (cont.) Include Page

– Allows the insertion of an XPage into another XPage in the same application

Panel

– A rectangular area of an XPage that can contain other controls

– Use panels to group a collection of controls on an XPage or to contain the entire contents of the XPage

•  Panels are implemented as <div> tags at runtime

79

Container Controls (cont.) Repeat

– Used to repeat other controls on an XPage •  Typically computed fields •  Alternative to using a view or data table control

Section

– Allows users to expand and collapse sections of an XPage

•  Sections are similar to panels but are collapsable

80

Container Controls (cont.) Tabbed Panel

– A collection of panel controls with tabs •  Each tab and tab panel can be designed individually

–  At runtime, users can click each tab to navigate among the panels

–  Tabbed panels are useful for conserving space on the XPage and reducing the need to scroll

Table

– A table with individual cells •  Equivalent to an HTML table •  You can insert core controls in table cells

81

Controls

82





83

Domino Design Elements The following Domino design elements support

XPage development

– Views – Forms – Script Libraries –  Image Resources – Style Sheets – Themes

84

One of these is required

Two Approaches to Development There are two approaches to designing an XPage:

– Create a new Domino application (.nsf) •  Create and design a new XPage in the new

application – Edit an existing Domino application (.nsf)

•  Create and design a new XPage in an existing Domino application

85

Starting from Scratch If you are designing a new application from scratch

– Then create the forms and views first XPages require a data source

– Domino forms and views are that data source

86

Form Design If the XPage will be the only UI for the data, then

the form design is simply a mechanism to define the fields ( a schema )

– All you really need to define is: •  Field Type •  Name

– No formatting or form logic is required – When creating the field names:

•  Use CamelCase •  Use complete

spelled out identifiers

87

View Design Views do not require any fancy formatting Lay out the columns in the order you want them to

be displayed in the XPage Flat (non-categorized) views are easier to

implement in XPages

– Categorized vews can be used, but there are some gotchas (more on this later)

88

Adding to an Existing Application The existing form and view designs of an

application can be used as the data sources for an XPage

– Even so, there may be some benefit to having XPage-specific form and view designs

•  Forms –  Existing forms computed for display fields do not transfer

over to the XPage data source at all – Radio button and check box fields on the Domino form can

not be implemented on the XPage natively

•  Views – Complex categorized views may not display/behave exactly

as you expect – Hidden columns are transferred to the XPage data source

but generally have no value 89

Adding a View to an XPage There are two ways to add a View to an XPage

– From the Data palette – By adding the view control

90

Adding a View from the Data Palette From the Data palette

– Select the view data source – Select the view columns to be added to the

Xpage – Drag and

drop the selected columns onto the XPage editor view

91 86

View Control Is Created on the XPage The result of dragging the view data source column

onto the XPage editor are:

– New view control created including navigation bar at top

– View column controls added for each column

92 87

Outline View with View control and column controls listed

Editor View with View Control

View Controls Properties

XPage vs. Normal Web Display

93

XPage Design

View Design

Adding Views Using the View Control Using the view control from the Container Controls

category of the Controls palette

– Drag and drop a view control onto the XPage editor view

94 89

Select Data Source for View Dialog Box In the “Show data from” field, choose either:

– Domino view – creates a View data source specific to this control

– View Data Source Name – references the XPage View data source

Check the columns to be included in the created view control

95

Very Subtle Differences If a new data source is created with the view

control, then the data source is a child of the View control and not the XPage

So? – These properties only show up in the All

Properties tab – The View Data source is scoped to the control

and not the page It is generally better to add View controls to the

XPage via the View control from the Controls palette instead of the Data palette

96

Difference in View Controls Data Sources

97

Data source is defined on the XPage

Data source is defined in the View Control

Adding a Domino Form to an XPage From the Data palette

– Select the fields that will be included on the XPage

– Drag and drop the fields onto the XPage editor window

– This will create a Table control with: •  Label controls based upon

the field name (why it’s best to use CamelCase field names)

•  Edit controls for each field

98 93

Adding a Domino Form to an XPage

99

Adding a Domino Form to an Xpage Before dragging the data source fields onto the

XPage editor, you can enable the Select Controls Dialog Box (disabled by default)

If enabled, it will display the Select Controls Dialog box before adding the fields to the XPage

100

Adding a Domino Form to an Xpage In the Select Controls dialog box

– Select/deselect the fields to be added Next to the control, optionally

change the control type from the drop down list

– There is no Radio Button or Check Box control

Optionally

– Check the box to add •  Submit Button •  Error Messages

101

Field Mapping

102

Domino Field Type Suggested XPage Control

Text Edit Box Date/Time Date Time Picker Number Edit Box

Combobox Combo Box Listbox List Box

Dialog List List Box Password Edit Box Authors Readers Names

Edit Box for single values List Box for multiple values

Rich text Rich text lite

Rich Text

Checkbox Combo Box - Then manually change in Source

Radio button Combo Box - Then manually change in Source

Adding a Domino Form to an XPage XPage design after fields with default submit

button and error messages have been added

Rendered in the browser

103 97

Document Options The XPage that contains the fields from a Domino

Form can be used to:

– Create new documents – Read existing documents – Edit existing documents

104

Associating the View and Form XPage to Each Other

Now that we have both the View and Form XPage, they can be linked to each another

On the View XPage, add a column link to load the Form XPage when it is clicked on

105 99

Select the column that contains the data that will be the link

Check the “Show values in this column as links” and select a document open mode

Associating the View and Form XPage to Each Other (cont.)

106

Choose which XPage to open when documents are selected from the View

XPage Associated with Documents Form Option

When this option is selected:

– Domino will look for an XPage with the same name as the value in the documents form field

–  If an XPage with the same name as the Domino form name cannot be found, then the value in the forms property for “Display XPage instead” will determine which XPage gets loaded

107

Results Rendered in the Browser

108

Adding Document Navigation Controls

The document is loaded from the View but … – There is no way to return to the view

•  Need to add a button that returns to the View XPage – There is no way to edit the document

•  Need to add a button that switches to edit mode – There is no way to cancel out of edit mode

•  Need to add a Cancel button to close edit mode and return to read mode

– Buttons that are out of context (like the submit button in read mode) should not be displayed

•  Need to add “hide when” logic to buttons based upon the state of the document

– There is no way to create a new document •  Need to add a create document link to the View control

109

Add a Button That Returns to the View XPage

Append a row to the Table control

– Click in last row, right click and choose “Insert Row Below”

From the Controls palette click and drag a Button control to the last row of the table

110

Add a Button That Returns to the View XPage (cont.)

In the Button section of the Properties tab:

– Change the label of the button to something more indicative of its purpose

111

Add a Button That Returns to the View XPage (cont.)

On the “onclick” Mouse event on the Events tab:

– Click the Add Action... button for Simple Actions – Choose the Open Page action and select the

name of the View XPage as the name of the page to open

112 106

Add a Button That Switches to Edit Mode

Append a row to the Table control From the Controls palette, click and drag a Button

control to the last row of the table Edit the name of the button

Add a simple action to switch to edit mode

113

Add a Cancel Button Append a row to the Table control From the Controls palette, click and drag a Button

control to the last row of the table Edit the name of the button

Change the Button type to Cancel

114

Add a Cancel Button (cont.) Select the XPage control In the XPage section of the XPage Properties tab:

– Change the “Next page (success or cancel)” field to the name of the View XPage

115

Add “Hide When” Logic to Buttons The majority of control properties have a grey

diamond next to them

– This denotes that the property is “computable”

Click the grey diamond next to the button’s “Visible” property

– Select “Compute value…” from the drop down list

116

Add “Hide When” Logic to Buttons The document data source name becomes a global object

(variable) Use the Boolean

isEditable() method to determine if the document is in Edit mode

When in Read mode, this method returns false so the submit button will not be displayed

When in Edit mode, this method returns true so the submit button will be displayed

Add the ! (not) operator to the beginning of the expression to reverse the logic

117 111

Add “Hide When” Logic to Buttons Once a properties value has been set to compute

– The word “computed” will appear in braces – The grey diamond will turn to aqua

118

Add a Create Document Link to the View Control

Drag a Button or Link control to the View XPage

119

Add a Create Document Link to the View Control

Change the Label to the text that will appear on the link

Select the "Open page" option in the Options section

– Choose the Form XPage to be opened

120

Domino Object Navigation

121





122

Coding Language Options JavaScript

– Client side •  JavaScript that is interpreted by the browser that is

displaying the XPage – Server side

•  JavaScript that is interpreted by the Domino Web server @Functions

–  JavaScript methods that are based on the functions of the same name in the Notes Formula Language

Java – Ability to call core JDK or custom class methods from

an XPage

123

Client-Side JavaScript Client-side JavaScript code is added to a control’s

events in the Events view

Controls that support client-side script will have a Client tab

– This tab has a code window and a list of events – This image shows where to add client-side

JavaScript for the onclick event

124

Limitations of Client-Side JavaScript When an event that uses client-side JavaScript is

triggered on an XPage: –  It is interpreted by the browser’s JavaScript

interpreter – This is similar to the way JavaScript code is run on a

traditional Web page – The client-side interpreter in the Web browser has

the following characteristics: •  It can access the Document Object Model for XML and

HTML •  It has access to client-script libraries only •  It can not access server JavaScript packages (libraries) for

accessing the document and performing other activities •  It cannot be used for the Domino @Functions •  It uses the standard JavaScript found in the browser

125

ID Attribute Is Re-Written The following is the tag in the source tab of the

XPage editor in Domino Designer:

However, the following is what is actually rendered

to the browser (HTML):

Notice how "view:_id1:" is prefixed to the value for the ID attribute

126

<input type="text" id="view:_id1:CustomerName1" name="view:_id1:CustomerName1" class="xspInputFieldEditBox">!

<xp:inputText value="#{document.CustomerName}" id="CustomerName1"></xp:inputText>

Accessing XPage Controls via Client-Side JavaScript

There are three options for accessing XPage controls via client-side JavaScript:

– Prefix the ID name – Use the server-side JavaScript getClientId()

function – Use abbreviated server-side syntax

127

Prefix the ID Name When referencing element names, the known

prefix can be added in front of the ID name using the following syntax:

This is not a recommended best practice

– Although it works, the prefix is not guaranteed to be consistent •  For example, if the XPage is included in another

XPage, then the default "include1" is also prefixed to the ID name

128

alert(document.getElementById("view:_id1:CustomerName1").value);

Use the SSJS getClientId() Function Client-side JavaScript has no access to the back-end

document There is, however, a global server-side JavaScript

function to access a control – The getClientID("IDName") function

But, how do you run server-side JavaScript from the client? – The following syntax allows server-side JavaScript

code to be included in client-side JavaScript events* Using this technique, the getClientID() function can be

invoked using the following syntax:

129 141

"#{javascript:<ServerSide JavaScript>}"

alert(document.getElementById("#{javascript:getClientId("CustomerName1")}").value);

Use the SSJS getClientId() Function When displayed in the browser, the Domino Web

server will return the following:

Notice how the server-side JavaScript code was replaced by the actual value (ID of the control)

130

"alert(document.getElementById("view:_id1:CustomerName1").value);!

Use Abbreviated Server-Side Syntax The previous technique can be simplified by using the

abbreviated syntax of: The following syntax can be used in place of what was

shown in the previous example: This will return the same results as the technique that uses

the getClientID function –  But it is shorter and easier to read –  This shortcut can be used for any JavaScript code that is

meant to be interpreted by the Domino server before rendering the page

–  This technique is considered the Best Practice for accessing XPage controls from client-side JavaScript

131

#{id:<ControlName>}!

alert(document.getElementById("#{id:CustomerName1}").value);

Client-Side JavaScript

132

Server-Side JavaScript Server-side JavaScript is interpreted by the Domino

Web server

Events on most controls can have server-side JavaScript

The advantages of server-side JavaScript is that the code has full access (security permitting) to all the Domino applications via:

– The Domino Object Model – @Functions

133

SSJS Events Server-side JavaScript supports the same events

supported by client-side JavaScript (i.e., Mouse events, Focus events, etc.)

In addition to these, server-side JavaScript also supports XPage events, Document events, and View events

Not all controls support every event

134

Computed Control Properties Computed properties are also coded using server-

side JavaScript

135

There Are Two Computing Conditions

Compute Dynamically Compute on Page Load

136

Compute Dynamically This script is executed whenever the page context

is refreshed

– When the page is initially loaded – When the page is saved – When the page is submitted

Dynamically computed scripts appear in the source view preceded by a pound (#) sign

137

<xp:text escape="true" id="computedField1" value="#{javascript:@Author();}"></xp:text>

Compute on Page Load This script is executed once

– When the page is loaded On Page Load scripts appear in the source view

preceded by a dollar ($) sign

138

<xp:inputText id="inputText1" value="${javascript:@Author();}"></xp:inputText></xp:view>

Declaring SSJS Variables The same syntax can be used when creating variables in

server-side JavaScript as when creating variables in client-side JavaScript

–  The following code statement declares the curSession variable and sets it to the global session object:

Because the global session object is actually an instance of the Notes Session Java class, the code could also be written using the server-side JavaScript-specific syntax

–  This syntax denotes the class type by separating the variable name and class type with a colon (:)

–  The following code statement produces the same end result as the previous statement but better defines what object type the variable is:

var curSession = session;

var curSession:NotesSession = session;

Writing Server-Side JavaScript The following libraries are available when writing

server-side JavaScript

140

Library Name Description

Global Objects Global objects can be accessed directly by name. It is not necessary to declare a global object prior to its use in the script.

Global Functions Like global objects, these functions can be called directly. It is not necessary to instantiate a global function prior to its use in the script.

DOM The DOM library represents XML documents Domino The Domino library represents the Domino Back End Classes

Runtime The Runtime library represents the runtime application returning Local and Time Zone information

Standard The Standard library represents the various data types, like Array, Boolean, etc.

XSP The XSP library includes utility classes for interacting with the XPage

@Functions JavaScript implementations of Common Notes @Functions

Getting and Setting Control Values Control values on an XPage can be manipulated via

the:

– getComponent() methods •  Getter and Setter Methods

141

Method Syntax setValue getComponent( id:string ).setValue( value );

getValue getComponent( id:string ).getValue();

Example of Getter, Setter Methods The Getter, Setter methods can be used to read and

set control contents when the XPage is in edit mode

142

Accessing Domino Objects Domino Back End Classes are available using

Notes<ObjectName> syntax – Session – NotesSession – Database – NotesDatabase – Etc.

Class names are case sensitive – This is not LotusScript – Almost right is the same as wrong

There are Global Variables that return Domino Objects – Session – The current NotesSession – Database – The XPage parent application – DocumentDataSource – The referenced Domino document – CurrentDocument – The current Domino document

143

Properties of Global Variables The global variables do not need to be declared

prior to calling their methods

144

Computed fields’ output in the browser

Server-Side JavaScript

145

@Functions When @Functions are used in XPage development:

– They are actually JavaScript methods that are based on the functions of the same name in the Notes Formula language

– The important point to consider is that these ported @Functions are coded using JavaScript •  So JavaScript rules and syntax apply •  Consider the following when using @Functions in

XPage development: – Names are case sensitive –  Parameters are separated by commas (,) not semicolons (;) –  Available only when coding server-side JavaScript

146

@Functions (cont.) Can be used in any Server-Side JavaScript editor Are not limited to manipulating Domino Objects

147

Populate List Box and Combo Box Controls with @DbColumn

The @DbColumn function returns an array of values from the specified column in a Domino view

– The @DbColumn function uses the following syntax: •  @DbColumn(dbName, viewName, colNumber )

148

Populate List Box and Combo Box Controls with @DbColumn

149

Input Data Type Description Example

dbName A String Array or List

Current server and application. Current server and a specific application.

Tip: If the XPage is in the same application

as the Domino View for the lookup, then use the @DbName function to return the

appropriate value

"","" "","XPagesJMP.nsf"

@DbName

viewName String View name or alias "SalesRepView"

colNumber Integer Integer of the column in the view to read values from. View column indexes start at 1.

2

@DbColumn Example Using the Same pipe separator { | } syntax that

Domino uses

– The first DbColumn returns the list of values to be displayed to choose from

– The second DbColumn returns the list of values that will actually be stored with the document

150

Use AJAX to Partially Refresh XPage After Selection Is Made

AJAX can be used to update XPage controls after a value from a Combo Box, List Box, or Radio Button is made – On the Events tab of the control where the value

is being selected •  Select the “onchange” event •  Under “Server Options” select “Partial Update” •  Click the “Select Element…” button to choose the

control to be updated

151

Use AJAX to Partially Refresh XPage After Selection Is Made

152

Use Container Controls to Update Entire Sections

If you need to update an entire section of the XPage:

– Place controls to be updated in a Container control •  Panel •  Section

153

@Functions

154

Java Any Java from the SDK can be called from any

Server-Side Script

The following code creates a variable using the java.lang.String class

– The toUpperCase() method of Java String class is called to uppercase the variable value

155

Demonstration

156





157

XPage Design Resources XPage Wiki

–  www.lotus.com/ldd/ddwiki.nsf Domino 8.5 Discussion Forum

–  www.lotus.com/ldd/nd85forum.nsf?OpenDatabase IBM developerWorks – All Things IBM

–  www.ibm.com/developerworks –  www.ibm.com/developerworks/lotus –  www.ibm.com/developerworks/lotus/documentation/domino –  www.ibm.com/developerworks/java –  www.ibm.com/developerworks/xml

158

XPage Design Resources (cont.) Bleedyellow Forum

–  www.bleedyellow.com/communities/service/html/communityview?communityUuid=120fc506-ca30-426d-a149-ee6f21916ca7

Extensibility API Documentation –  www.lotus.com/ldd/ddwiki.nsf/dx/

Master_Table_of_Contents_for_XPages_Extensibility_APIs_Developer_Guide

Extensibility API JavaDocs –  http://public.dhe.ibm.com/software/dw/lotus/Domino-

Designer/JavaDocs/XPagesExtAPI/8.5.2/index.html 159

XPage Design Resources (cont.) OpenNTF – Open Source Applications, Utilities, Samples, etc.

–  Extensibility library –  Mobile tools –  Dozens more

•  www.openntf.org XPages Blog

–  http://xpagesblog.com OneUI Framework Layout Documentation

–  www.lotus.com/ldd/doc/oneuidoc/docpublic/components/framework.htm?spriteson=false

XPages Wiki – Independent –  http://xpageswiki.com

160

XPage Design Resources (cont.) XPages Object Map

–  www.lotus.com/ldd/ddwiki.nsf/dx/XPages_Domino_Object_map_8.5.1

XPage Knowledge Collection –  www.ibm.com/support/docview.wss?

rs=899&uid=swg27014929

161

162

Resources — Client Code W3Schools.com – Good for Things Web

–  www.w3schools.com Dojo Toolkit – JavaScript Client Library

–  http://dojotoolkit.org SitePen Blog – Great Dojo Tips and Tutorials

–  www.sitepen.com/blog jQuery – JavaScript Client Library

–  http://jquery.com Blueprint CSS – CSS Framework/Great for column positioning

–  http://blueprintcss.org Elastic CSS – CSS Framework

–  http://elasticss.com

163

Resources — Client Code (cont.) Douglas Crockford – JavaScript Guru

–  www.crockford.com –  www.crockford.com/javascript

JSON – JavaScript Object Notation/Official Site –  www.json.org –  www.json.org/js.html

JS Lint – JavaScript Code Validator –  www.jslint.com

Mozilla Developers Guide –  https://developer.mozilla.org/en/JavaScript/Guide

163

164

Resources — Client Code (cont.) Firebug is an extension/plug-in for the Firefox browser

–  The Firefox browser can be downloaded at the following URL:

•  www.mozilla.com/en-US/firefox/personal.html –  Once the Firefox browser is installed, go to the following

URL to add extensions and plug-ins: •  https://addons.mozilla.org/en-US/firefox

Head First Series Books –  Head First HTML with CSS and XHTML –  Head First JavaScript –  Head First AJAX

•  http://headfirstlabs.com

164

Resources — Server Code JSFTutorials.Net – Series of Java Server Faces Tutorials

–  http://jsftutorials.net ODF Toolkit

–  http://odftoolkit.org iText

–  http://itextpdf.com Bruno Lowagie, iText in Action (Manning Publications, 2010).

–  ISBN: 1935182617 Apache FOP

–  http://projects.apache.org/projects/fop.html Apache POI

–  http://poi.apache.org 165

Resources — Server Code (cont.) IBM developerWorks Java Tutorial

–  www.ibm.com/developerworks/views/java/libraryview.jsp?search_by=tutorial,+perry&cmp=dw&cpb=dwjav&ct=dwnew&cr=dwnen&ccy=zz&csr=082610

Head First Series Books –  Kathy Sierra and Bert Bates, Head First Java, Second Edition

(O’Reilly Media, 2005). –  Bryan Basham, Kathy Sierra, and Bert Bates, Head First Servlets

and JSP, Second Edition (O’Reilly Media, 2008). –  Brett McLaughlin, Gary Pollice, and David West, Head First

Object-Oriented Analysis and Design (O’Reilly Media, 2006). •  http://headfirstlabs.com

166

Other Resources W3C – Standards Body for Web Technologies

–  www.w3c.org BuiltWith Trends – Site that trends Web site development tool

use –  http://trends.builtwith.com

TIOBE – Programming Language Trends –  www.tiobe.com/index.php/content/paperinfo/tpci/index.html

HTML 5 Rocks – HTML 5 Example Site –  www.html5rocks.com

Online CSS constructor –  www.constructyourcss.com

167

Other Resources (cont.) Widget Gallery

–  www.ibm.com/software/ucd/widgetgallery/widget_home.html Taskspeed – Performance Of CSJS Frameworks

–  http://dante.dojotoolkit.org/taskspeed/ Planet Lotus – Blog Aggregator (This is the only one you

really need) –  www.planetlotus.org

XPages 101 – Matt White Training Videos –  XPages101.net

Notes in 9 – David Leedy XPage Screen Casts –  http://notesin9.com

168

Other Resources (cont.) Tip of the Iceburg – Tim Tripcony

–  www.timtripcony.com Paul Withers

–  http://hermes.intec.co.uk/intec/blog.nsf Mark Hughes

–  http://dominoextnd.blogspot.com/ Kuler – Color Scheme Site

–  http://kuler.adobe.com/#themes/rating?time=30 Color Scheme Generator

–  www.perbang.dk/color+scheme Single Landing Page for all IBM Documentation

–  www.ibm.com/developerworks/lotus/documentation 169

Other Resources (cont.) TLCC – The Learning Continuum Company

–  Domino Designer 8.5.1 •  Free TLCC course on using DDE

–  www.tlcc.com/admin/courses.nsf/lookupcoursecode/DD85INTR?opendocument&viewname=R85Cur

–  Notes Client Based Training •  Java (Intro and Advanced) •  XML, Web Services •  XPages (Intro and Advanced) •  JavaScript

–  www.tlcc.com

170

Your Turn!

171

How to contact me: Paul T. Calhoun [email protected]