XPages: No Experience Needed

SHOW 111
XPages: No Experience Needed
Kathy Brown | Consultant
David Leedy | Collaborative Solutions Developer

© 2013 IBM Corporation
© 2013 RunningNotes

Agenda
 Who We Are
 What We Are Building
 What Are XPages?
 Creating the Application
 Refining the Application

2 © 2013 IBM Corporation © 2013 RunningNotes

Who We Are
 Kathy Brown
– Consultant at PSC Group, LLC
• www.psclistens.com
• @pscgroup
• kbrown@psclistens.com
– Blogger at www.runningnotes.net
– IBM Champion
– Co-author of Lotus User Group’s Notes Dev Tips newsletter
– Speaker at Lotusphere and user group events around the world
– Twitter addict @RunningKathy
• and at last count, 14 other accounts
– Runner
– Mom
– Geek
– Nerd Girl


Who We Are
 David Leedy
– Customer
– IBM Champion
– NotesIn9.com
• 27 + hours of Free XPages Videos
• 160,000+ total views/downloads
• Jumpstart Videos
• index.notesin9.com
– XPages Cheatsheets
• Original XPages Beginner Cheatsheet
• Social Tools Cheatsheet
• Online URL CheatSheet (Beta)
• Downloadable demo app and files
• cheatsheet.notesin9.com

– Contact Info
• @DavidLeedy
• dleedy@notesin9.com


IBM Trademarks
Domino®
IBM®
IBM SmartCloud™
Lotus®
Lotus Notes®
Lotus Organizer®
LotusLive™
LotusLive Notes™
LotusScript®
Lotusphere®
Notes®

http://www.ibm.com/legal/us/en/copytrade.shtml#section_1


Agenda
 Who We Are
 What are XPages?


What We Are Building
 An XPages Help Desk Application
– User can enter tickets
– Resources can be assigned
– Comments can be added
 What we will need
– Basic CRUD
• Create
• Read
• Update
• Delete
 What we will use
– XPages components
• OneUI
• Core Controls
• Extension Library
• Custom Controls
• and more!


Agenda
 Who We Are
 What are XPages?


What are XPages?
 New Design Elements and tools for creating web applications
 Embraces standard languages
– HTML, CSS, JavaScript, Java
 Built on top of Java Server Faces
– XPages is a front end that Domino Developers will understand
 Everything you code gets placed inside of Java Objects
– You never need to deal with those Java Objects though!
 You do not NEED to know Java to build XPages apps
– But it will help and should be something to strive for
– Java in XPages is somewhat similar to LotusScript Custom Classes


What does XPages Fix from “Classic” Notes/Domino?
 Separates UI from Data
– Allows multiple Data sources per Page
– Easy access to data from other databases
 Improves Data capabilities
– Allows @DbLookup from inside a view
• Similar to a JOIN in relational DB’s.
– Use Java Objects (Beans) as data source
– Iterate your data anyway you want via “Repeat Control”
 Runs inside Notes Client (XPiNC - XPages in Notes Client)
– Replicate your web applications


New Design Elements
 XPage
– Similar to Notes Form
• But not really as you can have none or multiple datasources
• Data source can be:
» NotesDocuments, NotesViews,Java Beans, and more...
• It’s often used more as a container to hold custom controls
 Custom Control
– Similar to Subform
• But not really as you can have none or multiple datasources
• Just like XPages
• Can be used more then once on a page
• Can accept Parameters that you define later
• Allows high reusability
• Can not be viewed in the browser. They only work on an XPage
• Often Custom Controls are used to contain the graphical layout of your app


New Design Elements
 Sever Side JavaScript Library
– Similar to LotusScript Library
– Allows you to create reusable functions using SSJS
– It’s not really “JavaScript” but it has the same syntax
• This allows additional capability
• @Formulas
• Domino Object Model
• Java Objects
 Themes
– You can assign a CCS file and it’ll be available on every page of your app
• Like a Global “Use” statement in LotusScript
– Allow consistent look and feel across apps
– oneUI and WebStandard are built in
– You can create your own
• But always extend a server theme as they contain needed Dojo files
– Themes can override controls as well
• More advanced but very powerful


XPages:Scoped Variables
 Scoped Variables
– In memory objects to store data
– No need to rely on cookies / URL parsing
• but you still can if you want
 applicationScope
– Like a database profile document
– Available to all users
• Store Application settings and common lookups that all users need
 sessionScope
– Life of the user session
• Store things specific to the user.
• Preferences, shopping cart, etc...


XPages:Scoped Variables continued
 viewScope
– Life of the current Page
• Store value of a current search, or items from a particular document
 requestScope
– Life of a single request
– Very short - just for data you’re currently processing

 Do NOT try and put Domino Objects (document, view, etc...) in Scope
– They will likely get recycled when you least expect it.
– For a document, just store a UNID as a string and grab the document again


Getting Started Building the App
 The most recent version of the starter files will be available at http://notesin9.com
and http://runningnotes.net
 We’re using Domino and Designer 8.5.3
– You need to be using the Update Pack or OpenNTF Extension Library
• Update Pack is available from IBM
• Ext. Library is at http://extlib.openntf.org/
 What is the Update Pack / Extension Library?
– They are add ons to the Domino Server / Designer
– Adds over 50 new tools and controls designed to speed up your application
• Tools for layout, Dojo integration, etc.
• Application layout control, which provides the framework for this application!
– Extends the core product without having to wait for next version
 Everything you see here should work on:
– Domino/Designer 8.5.2 with Ext. Library
– Domino/Designer 9.0 beta
• No update pack or ext. library needed as it’s built in
– However, these versions have not been tested with the application


Starter Files
 We have a downloadable kit available to start
 This kit contains :
– Starter database
– Finished Database
– Slides
– Script Snippets
 Starter Database contains several forms and views but no XPages code
 Download the kit to your machine and extract the files
 Copy the starter application to your Notes Data Directory
– usually something like c:program fileslotusnotesdata


Starter Database
 Some basic elements have already been added
 Forms
– form_comment
– form_resource
– form_ticket
– keywords
 Views
– vwComments
– vwCommentsByKey
– vwKeywords
– vwTickets
– vwTicketsByStatus
 Example Documents
– Some keyword documents
– Some ticket documents


Coding on Domino Applications
 It’s best practice to use a local template (.ntf) file for coding your application
 You would then refresh a version of the application that runs on the server with this
local template
 This link between the databases is made my using the design tab of the database


Refreshing from Template
 To refresh your code from the template
 Go to the server database then using either the file menu from the last slide, or
right clicking on the icon as shown below - click “Application” - “Refresh Design”


Demonstration Cheating
 For the purposes of this demo we will not use a template and we’ll work directly on
the server.
 This is convenient when starting a database as we’ll be doing a lot of testing as we
go. So this eliminates a lot of “Refresh Design” steps.
 Typically when an application reaches a certain stage of development it can be
copied to an .ntf file to become a true template.


Open the Starter application from Domino Designer


 Make sure to choose Local - then find on your hard drive
– It should have been first copied to your Notes Data Directory


Working Sets
 Working sets are ways in Designer to group and organize your applications.
– If using a working set you might see this screen. Choose Yes to add it.
– If you’re not using a working set it will just be added to your application list


Copying to server
 Right click on the starter file and copy it to your server if you’re using one


Opening from Server
 Finally open the server version just like we did the local


Results
 You end up with 2 database. The local and a COPY on the server.
– Since we did a file copy these will not replicate
– We will focus on the server for this demo - you can right-click and “Remove” local if you
want.
– Using the server is more convenient for rapid testing and allows security to work


Agenda
 Who We Are
 XPages


Beginning to Code
 Goals
– Setup some application properties
– Create an overall layout for the web application
• Will be reusable so any pages we add get the same look and feel
• Add the ability to Login / Logout to the app
– Create a home page
– Test


Set the Theme
 Application Properties - XPages Tab - Set Application theme to:
– oneuiv2.1
– All lowercase
– This makes a base css and dojo JavaScript resources available
– oneuiv2.1 is a theme provided by Domino and gives our application the “look and feel”
similar to mail, the teamroom, etc.
– Using oneuiv2.1 means we do not have to individually style anything, although we can if
we want to (more on this later)


Create the Layout for the application
 2 Custom Controls
– 1 for the Main Layout
– 1 to hold a Navigation Bar on the left side
 Update Pack 1 / Extension Library required for this*
– Many controls are added to the core product
– App Layout Control provides the overall look and feel
• The App Layout Control can be added to each XPage for consistent navigation and
layout throughout the application
– Form Tables and Form Rows allow us to easily layout fields
– Tool Tips and Dialogboxes are available
– Many many more tools available

* Extension Library OR UP 1, not both


Create layout_Main
 Create a custom control to become the main layout of the application
 Custom controls - New Custom Control - “layout_Main”


Drag “Application Layout” onto Design Area
 Just click OK on the wizard


Should look like this
 Green dots are areas for future custom controls
 You can drag controls onto the green dots (targets)
 Placing a control onto a target on the layout means the control will be used
whenever the layout is used
 Enabling a target means different controls may be used on different instances of
the layout


Enable Green Dots for Middle Column
 Select the layout control by clicking on it. Then use properties tab


Embrace the Source tab
 Note by clicking the Middle Column that the source has updated.
– This callback allows Custom controls to be added later
– We click the Middle column as that will be the placeholder for the page
– We do not click the left column as we’ll add the nav menu to the layout custom control
itself. This way it will be available to every page.


Create ability to Login / Logout
 Select the App layout control that you dropped on the page
 Add Login and Logout Node*

*A “node” is just terminology for the
structure, i.e. “leaf node”

A “container node” can contain
several “Page Link nodes”

Login and Logout Node simply
provides a spot on the layout to
have a link to ... login and logout

We’ll see a Page Link Node later...


Remove the Label
 This SHOULD make an Automatic Login and Logout node
– But There is a bug in Update Pack 1
– Workaround will be to create a manual logout node
• We’ll do this in just a bit


Login/Logout Workaround
 Before we create logout - Display the current user name
 Create another node, a User Node


Showing current user
 Server Side JavaScipt is used to create a NotesName object.
– Compute the label of the user name
– Click the blue diamond next to label
– Choose “Compute Value”
– Enter the code below
 If the current user is not “Anonymous”
we display a little welcome message

// Create Notes Name Object from the current effective user
var userName:NotesName = session.createName(session.getEffectiveUserName());
// If the user is not Anonymous then return a welcome message
if (userName.getCommon()!="Anonymous") {

return "Welcome, "+userName.getCommon()+"!";
}


Server Side Javascript
 If that was your first real exposure to Server Side Javascript (SSJS),
congratulations!
– That wasn’t so bad, right?
 A few things to note:
– Syntax is similar, but not the same to LotusScript
– Semicolons, you need them
– // is a comment, not ‘
– Proper Capitalization is important
• @Unique() will work, while @unique will not
– Oh! And you can use some @Formula (not all, but quite a lot)
• Parentheses are important


Adding Logout Fix
 Add another node, a Basic Node like before
– Set the label to “Logout”
– Compute the values for href
• This makes the node a link that logs the user out and redirects them to the page they
were on

href property computed value:
return facesContext.getExternalContext().getRequest().getContextPath() +
"?Logout&redirectTo=" + facesContext.getExternalContext().getRequest().getContextPath()


Adding Logout Fix
– Compute the rendered property
• This returns true (Logout node is visible) if the user is logged in, ie not Anonymous

rendered property computed value:
var uName = session.getEffectiveUserName();
if (uName == "Anonymous") { return false; }

else {

return true;

}


Home Page
 Create a new XPage called home.xsp
– Custom controls are never rendered directly to the browser. They must be placed on an
XPage.


Drag layout_Main onto page
 Note the green dot is back. This is because we clicked the middle column earlier
 We will use this to add different controls to different pages


Check the Source
 Note: all that does is create a tag to represent the custom control


Drag a Panel onto the Green Dot
 In Source mode this creates a facet tag. You can easily add content in here. This is
the “body” of your web page
 A panel is a container for other controls


Check the Source
 In Source mode this creates a facet tag. You can easily add content in here. This is
the “body” of your web page
 Content goes between the <xp:panel> tags


Add some text to your home page
 Gives us a place holder for later
 You can use source or design - Save this page and close


Set the Launch - Go back to Application Properties

On the launch page set it to
Open designated XPage of
“home”.
Don’t forget to save and
close this.


Now you should be able to Test

* If you are working locally, you’ll need to add Anonymous with access in the
ACL in order to preview


Initial Home Page
 Should look similar to this
 Note the blue and black banner bars on the top
– That styling is thanks to our theme
 Note the “Login” and links on the bottom of the page
– Those elements are from the layout control


Summary
 We have an Application in progress
 We inherited some forms and views from the starter database
 We setup our application properties
– We added a theme and set the default home page
 Created a custom control for are application layout
 Created a home page and added the layout control
 Added a panel - which will render as an html <div> to the main body and added
some content.
 Tested in the browser


Next Up
 Create Custom Control for the Help Ticket
 Create Custom control to View tickets
 Create a Custom Control for the Navigation menu list


Create Custom Control for Ticket
 New Custom Control - Name it cc_Ticket
 Note we’re using a prefix to separate controls for layout from other custom controls


Create Data Binding
 We want to bind this control to a document
– As mentioned earlier, data and UI have been separated
• data on the form, UI on the XPage
– Binding allows us to put them back together however we want
• i.e. we can have multiple data sources on a single XPage
 In properties Data Tab - Add - Domino Document


Create Data Binding...
 select form_ticket and name the data source ticketDoc


Add Code to before Page Load event to pre-populate fields and
scoped variables

In Outline the focus must be on
custom control. Then in Events
tab find beforePageLoad


Add This code from Script Snippets
 This code creates a unique key and Date for a new document
 It also puts the key field into viewScope memory for later use


Here’s how this code looks in source
 Note the tag and use of javascript inside the curly braces
– Comments Describe the code

<xp:this.beforePageLoad><![CDATA[#{javascript:if (ticketDoc.isNewNote()) {
// If this is a new document - generate a unique key
var tempKey = session.evaluate("@Unique");
// Add the unique key to the document itself
ticketDoc.replaceItemValue("ticketKey", tempKey );
// Add the key to viewScope so we can use it later as needed
viewScope.put("vsTicketKey", tempKey);
// Set the ticket Date to current Date/Time
ticketDoc.setValue("ticketDate", @Now());

} else {
// This is not a new document so retrieve the key and put in viewScope
viewScope.put("vsTicketKey", ticketDoc.getItemValueString("ticketKey"))
}}]]></xp:this.beforePageLoad>


Adding Fields to Your Page
 Drag the FormTable control to your control
 FormTable contains formRow and can also optionally contain formColumn tags
 This gives you a nice CSS styled layout of your labels and fields
– Without needing to know or change CSS (although you can change it if you want to)


Update Label Position
 From the Form Table’s All Properties panel, change the labelPosition to “left”
 This will allow you to move all labels later if desired with one click (rather than one
for each label)
– Note other properties like formTitle


Add Title to Form Table
 Select the Form table
 Add the formDescription and formTitle


Drag form layout row onto form layout table body’s green dot
 This creates 1 row that will contain a label and a field, automatically


Adjust Label Placement on the row
 From the Form Layout Row, change the labelPosition to “inherit”
 Changing the label position will now be one click on the Form Layout Table (the
one we just set to “left”)


Check the Source


Set up the first form layout row
 Set Label to “TicketID”
 Drag Computed Field to right most Green Dot


Bind computed Field to “ticketKey” field
 On the Value tab change “Bind to” to “ticketKey”
– Note the data source is “ticketDoc” which we added to the control earlier


Check the Source
 Note: This is a formRow inside a formTable tag. We are about to add multiple rows
 To get multiple fields on a row there is also a formColumn tag which allows you to
add more columns. This app does not use Columns.

<xe:formTable
id="formTable1"
labelPosition="left">
<xe:formRow
id="formRow1"
labelPosition="inherit" label="Ticket ID">
<xp:text
escape="true"
id="computedField1" value="#{ticketDoc.ticketKey}">
</xp:text>
</xe:formRow>
</xe:formTable>


Add the Ticket Date field
 We will continue filling out the fields for the ticket form. Same principle but not all
will use the computed field control. Most we want editable.
 Next add the date field by starting to paste this under the last </xe:formRow> tag in
source
 This is the row for “ticketDate”
<xe:formRow
id="formRow2"
label="Date"
labelPosition="inherit">
<xp:text
escape="true"
id="computedField2"
value="#{ticketDoc.ticketDate}">
<xp:this.converter>
<xp:convertDateTime
type="date"
dateStyle="short">
</xp:convertDateTime>
</xp:this.converter>
</xp:text>
</xe:formRow>


Changing the Display properties
 The source code on the previous slide contains a converter. This is represented in
the GUI design on the value tab and the display type


Add the Caller name field
 Note the use of the Name Picker <xe:namePicker> control
– The “for” of the namePicker needs to match the ID of your Target control
– Typically NamePickers require you to be logged in to work since your address book likely
has higher security

<xe:formRow
id="formRow3"
label="Caller"
<xp:inputText
id="inputText1"
value="#{ticketDoc.ticketCaller}">
</xp:inputText>
<xe:namePicker
id="namePicker1"
for="inputText1"
dialogTitle="Select the caller">
<xe:this.dataProvider>
<xe:dominoNABNamePicker></xe:dominoNABNamePicker>
</xe:this.dataProvider>
</xe:namePicker>
</xe:formRow>


Combo Boxes
 We’re about to add several Combo boxes
 You can hard code values, compute values, or do a combination
 If you use @DbColumns() or @DbLookups() to get the values watch out for the 64k
limitation that they still have


Add Ticket Category
 This is a combo box. Note there is Server Side JavaScript Code for looking up the
values
<xe:formRow
id="formRow6"
label="Category"
labelPosition="inherit"
for="category1">
<xp:comboBox
id="category1"
value="#{ticketDoc.ticketCategory}">
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript://We start with a blank array
and concat choices, so the first item in the list is blank.
//that way, we can validate whether or not the user made a selection
var mychoices = new Array("");
var mydb = new Array(database.getServer(),database.getFilePath());
var myotherchoices = @DbLookup(mydb, "vwKeywords", "category", 2);
var mytotalchoices = mychoices.concat(myotherchoices);
return mytotalchoices;
}]]></xp:this.value>
</xp:selectItems>
</xp:comboBox>
</xe:formRow>


ComboBox Code should look like this:


More Combo boxes
 We’re going to do three more combo boxes for Platform, Priority, and Status
– They will work exactly the same. The only difference is the field we’re binding to and the
keyword that we pass into the view


Now add the row for Platform
 Note the change in value for each field, and different keyword in the DbLookup

<xe:formRow
id="formRow7"
label="Platform"
for="platform1">
<xp:comboBox
id="platform1"
value="#{ticketDoc.ticketPlatform}">
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript://We start with a blank
array and concat choices, so the first item in the list is blank.
//that way, we can validate whether or not the user made a
selection
var myotherchoices = @DbLookup(mydb, "vwKeywords", "platform", 2);
return mytotalchoices;}]]></xp:this.value>
</xp:selectItems>
</xp:comboBox>
</xe:formRow>© 2013 RunningNotes
76 © 2013 IBM Corporation

Now add the row for Priority

<xe:formRow
id="formRow7"
label="Priority"
for="platform1">
<xp:comboBox
id="platform1"
value="#{ticketDoc.ticketPriority}">
<xp:selectItems>
selection
var myotherchoices = @DbLookup(mydb, "vwKeywords", "priority", 2);
</xp:selectItems>
</xp:comboBox>

Now add the row for Status

<xe:formRow
id="formRow7"
label="Status"
for="platform1">
<xp:comboBox
id="platform1"
value="#{ticketDoc.ticketStatus}">
<xp:selectItems>
selection
var myotherchoices = @DbLookup(mydb, "vwKeywords", "status", 2);
</xp:selectItems>
</xp:comboBox>

Add A Default Value for the Status ComboBox
 Select the status field
 On the Data tab, enter “Open” for the default value


Add the Description Row
<xe:formRow
id="formRow5"
label="Description"
<xp:inputTextarea
id="ticketDescID"
value="#{ticketDoc.ticketDescription}"
style="width:60%;height:3em">
</xp:inputTextarea>
</xe:formRow>

 Note the “style” line - this is to make the size of the field wider
– Any style markup on the control overrides the theme


When all that is done your design screen looks like:


Add a Tool Tip
 This is a common Dojo element bade easy with the Upgrade Pack / Ext. Library
– Drag a Tooltip below your form table layout


Configure ToolTip
 Enter the Label of the Tooltip
 Enter the “for” value. This is the ID of your control for the field “ticketDescription”
– Note - it’s the ID of the control - not the name of the field


Adding Buttons to the Form Table
 The formTable contains a footer facet. Drag a Panel onto the green dot.

Note what the change looks
like in source. We’ll be
working here for the buttons
by adding code inside the
<xp:panel> tags


Adding the Save button
 Inside the new Panel drag a button to the panel


Save Button Properties
 We can compute whether or not the button is visible
 Either enter the code in the source pane, or click the blue diamond next to “Visible”
on the Button tab, or click the blue diamond next to “rendered” on the All Properties
tab
– The “Pretty Panes” contain common properties. All Properties contain everything

// Hide button if it's in save mode
return ticketDoc.isEditable();


Save Button Properties...
 In order to make the button *do* something, click on the Events tab of the button
 Click “Add Action...”, change the Action to “Save Document” and the Data source
name to “ticketDoc”


Adding the Close Button from source
 Next, inside the same panel under the </xp:button> add the code below
– Or you could drag another button, set the label to “Close” and do the Open Page Simple
Action

<xp:button
value="Close"
id="button2">
<xp:eventHandler
event="onclick"
submit="true"
refreshMode="complete">
<xp:this.action>
<xp:openPage
name="$$PreviousPage"></xp:openPage>
</xp:this.action>
</xp:eventHandler>
</xp:button>


Adding the Edit Button via source
 Note as we’ve seen before we’re computing when to render this button
– the “!” in the beginning reverses the True/False value
– We want a false of the ticketDoc is editable

<xp:button
value="Edit"
id="button3">
<xp:this.rendered><![CDATA[#{javascript:// Hide button if it's
in edit mode
!ticketDoc.isEditable()}]]></xp:this.rendered>
<xp:eventHandler
event="onclick"
submit="true"
<xp:this.action>
<xp:changeDocumentMode
mode="edit"
var="ticketDoc">
</xp:changeDocumentMode>
</xp:this.action>
</xp:eventHandler>
</xp:button>

Forcing a Space
 After each button tag add  
 This forces a space

</xp:button>
 


cc_Ticket status check
 Should look like this. Don’t forget to save!!


Summary
 Created Ticket Custom control
– Used computed Fields, Edit Box, ComboBox, and Multi-line Edit box
• Created Lookups for our comboboxes
• Added some basic CSS to style a field
– Used Form Rows to give us a nice layout
 Created Save, Close and Edit buttons
– Added appropriate rendering


Create A Custom Control to View Tickets
 Create a new custom control as before.
 Call it cc_Tickets and find the beforePageLoad event
 Add via Script Editor:
 viewScope.put(“vsStatus”, “Open”)
– This is an in memory scoped Variable that will live for the life of the page. We’re setting
the default status we want to see to “Open”.


Add A Panel To Select Type of Tickets
 Drag a Panel onto the page.
– Give it the id of “statusPanel”
– Could also be added directly in source after the beforePageLoad tag

<xp:panel id="statusPanel">

</xp:panel>


Inside the Panel add a Combobox
 This gets all the tickets’ status values and returns them as options for the user to
select from
 We will bind the value of the Combo Box to the viewScope var we set earlier
 Once a value is selected (“onchange”) the panel containing the view (“statusPanel”)
will get refreshed
 This time we’re mixing a hard coded option of “Choose Status” which is the default
with @DbColumn code
– To get our status we’ll lookup from existing tickets and using @Unique() to return 1 value
for each status
– The reason for this is to only show statuses where we have actual
 Every time the Combo Box is changed a partial refresh is triggered against the
panel


Inside the Panel add a Combobox
<xp:comboBox
id="comboBox1"
value="#{viewScope.vsStatus}">
<xp:selectItem
itemLabel="<<Choose Status>>"></xp:selectItem>
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript:// Not the most robust solution.
Has a 64K limit and some other issues
// But @Formulas still work in XPages
@Unique(@DbColumn("","vwTicketsByStatus",1));}]]></xp:this.value>
</xp:selectItems>
<xp:eventHandler
event="onchange"
submit="true"
refreshMode="partial"
refreshId="statusPanel">
</xp:eventHandler>
</xp:comboBox>


Add the View
 Drag the Container Control “View” onto the Design pane inside Panel
 The Select Data Source for View dialog appears
 Set the view to be: vwTicketsByStatus
 Deselect $5 UNID - we don’t want to display it


View Control on your page
 The view is automagically created, including a pager


Add a Checkbox to the first column
 Select the first column
 Display Tab - select “Check box” - then Save the custom control


Adding Links to the Document
 In order for users to open the documents shown, we need to make them display as
links
 Select the ticket key column
 On the Display tab, select “Show values in this column as links”
 For our application, we will choose “Read-only” as the document open mode


Filtering the View
 We created the combobox so users could select which type of tickets to see
– The combobox sets a viewScope
 Now we want to filter the view to match the value in the combobox
 Select the View Panel
 Go to the Data tab
 On Filter by column name, click the blue diamond to compute value and enter:
return viewScope.get("vsStatus")
 Check off Exact match


Customize the CSS on the View
 From Resources, Style Sheets, click New Style Sheet Called “application.css”
 Save and close


Adding CSS
 Add the following code
 Save and close
 These classes will add shading to the odd rows
 The “HOVER” classes add different shading (and font color and weight) when the
mouse hovers over the rows

.oddRow {
BACKGROUND-COLOR: RGB(248, 248, 248);
}
.oddRow:HOVER {
color: #FFFFFF;
font-weight:bold;
}
.evenRow:HOVER {
color: #FFFFFF;
font-weight:bold;
}


Add the New CSS Resource to your Custom Control
 Include the style sheet as a resource on your custom control
 Note: Since this CC will always be shown inside of “layout_Main” you could also
add it there. Then it would be available for any future Custom Controls or XPages


Customize the CSS on the View
 On the cc_Tickets custom control, select the View Panel
 On the All Properties tab, enter “oddRow, evenRow” to rowClasses
 That’s it! Just like the styling markup directly on our description field overrides the
theme, our CSS resource applied to the control also overrides or “extends” the
theme


Adding Buttons to work against selected documents
 We’re going to add buttons for:
– Delete
– Close
– Waiting
– ReOpen
 We’re going to create a single custom control for the buttons and keep all our code
in one place
– We will create a script library to hold this code.
 We’re going to pass in properties at runtime to control the buttons


Create a SSJS Script Library
 Code - Script Library - New Script Library
– Make sure to choose Server JavaScript
– We’re going to add functions that we’ll use shortly


Add Function for getSelected
 This function will return an array with the selected documents’ IDs

function getSelected(viewName:string) {

// Pass in the name of a viewPanel and return the
selected ID's as an array

print("Running Array")

var viewPanel=getComponent(viewName); // this gets a
hold of the viewPanel

var docArray = viewPanel.getSelectedIds(); // This gets
the array of selected documents

return docArray

}


Add function for processDocuments
function processDocuments(action:string, array) {

//Based on the Action that's passed in, update the documents

// Loop through all the documents

var doc:NotesDocument

print("Length: " + array.length)

for(i=0; i < array.length; i++) {

var docId=array[i];

doc = database.getDocumentByID(docId);

// Switch is like a "Select Case" in LotusScript

switch(action) {

case "Delete":

doc.removePermanently(true);

break;

case "Close":

doc.replaceItemValue("ticketStatus", "Closed");

doc.save();

break;

case "Waiting":

doc.replaceItemValue("ticketStatus", "Waiting on User")

doc.save();

break;

case "Open":

doc.replaceItemValue("ticketStatus", "Open");

doc.save();

break;

default:

print("should Never get here");

}

}
doc.recycle()

}


Add function for getTicketCounts
function getTicketCounts() {

// Return a Map of the ticket types and counts

// TreeMap is different then HashMap as it's Sorted by the key value

var ticketMap:java.util.TreeMap = new java.util.TreeMap(java.lang.String.CASE_INSENSITIVE_ORDER);

var myView:NotesView = database.getView("vwticketsByStatus");

var vec:NotesViewEntryCollection = myView.getAllEntries();

var entry:NotesViewEntry = vec.getFirstEntry();

var tmpEntry:NotesViewEntry = null;

// We need some temp. variables

var tmpStatus:string = "";

var tmpCount:integer = 0;

while (entry != null) {

tmpEntry = vec.getNextEntry();

// Get the current Ticket Status - Using ﬁrst column value of the view.

// This is faster then getting the actual NotesDocument

tmpStatus = entry.getColumnValues()[0]

// Get the count from the map for the current status

tmpCount = ticketMap.get(tmpStatus)

// Now add back to the Map the new count

ticketMap.put(tmpStatus, tmpCount + 1)

// Recycle because Admins don't appreciated it when the server crashes.

entry.recycle();

entry = tmpEntry;

}

return ticketMap;
}


Looking at the SSJS Library
 The first 2 functions should look like this:


Save Script Library and exit
 XPages and Custom Controls can access Script Libraries as resources. We will
add it to the control later.


Create button custom control
 New Custom Control
 call it btn_ProcessDocuments


Add the properties
 Find Property Definition under the Properties Tab.
– Add a “New Property” for viewPanelName, action, and buttonName
– Each type should be string
 Property definitions are items for passing in information to a custom control
– We will pass in information like “action” and our script will take that information and
determine what will happen when the button is clicked
– This is what allows the same custom control to be used for our different buttons


Adding a Script Library
 In the Resources tab, click “Add” and select “Javascript Library”
 Then select the SSJS Utilities javascript library

<xp:this.resources>
<xp:script
src="/SSJS Utilities.jss"
clientSide="false">
</xp:script>
</xp:this.resources>

Add a button to the control
 compositeData is an object available to SSJS of all the properties and values
 Use “compositeData” from the property definitions created earlier, to get the name
of the button

<xp:button
id="button2"
value="#{javascript:return compositeData.buttonName}">
</xp:button>


Finishing the button
 In the “onclick” event call code in the script library to process documents
 Save and Close

<xp:eventHandler
event="onclick"
submit="true"
<xp:this.action><![CDATA[#{javascript:var array =
getSelected(compositeData.viewPanelName);
processDocuments(compositeData.action, array)}]]></
xp:this.action>
</xp:eventHandler>


What does that code do?
 compositeData is an object that lets you access the custom properties
– These properties will be set later when the custom control is added to an XPage or other
custom control
 We will compute the label for the button at run time.
– Example we might want the buttons to show different languages
 We will use the viewPanel name to determine the selected documents
 We then use the action parameter to pass in the selected documents and desired
action to our script library


Add the button custom control to cc_Tickets
 Open the cc_Tickets Custom Control that was created earlier
 Above the view Panel add button custom control


Updating the Custom Properties
 Adding values to the Custom Properties allows the control to be customized for
each instance
– Remember we created the Property Definitions earlier, this is where we input the values
for this specific instance


 Use Source to quickly Add Buttons for setting the ticket status to: close, Waiting,
and Open
– Note forced spaces in between for niceness
 
<xc:btn_ProcessDocuments
action="Close"
buttonName="Close Tickets"
viewPanelName="viewPanel1"></xc:btn_ProcessDocuments>
 
action="Waiting"
buttonName="Set to Waiting"
viewPanelName="viewPanel1">
</xc:btn_ProcessDocuments>
 
action="Open"
buttonName="ReOpen">
<xc:this.viewPanelName><![CDATA[#
{javascript:"viewPanel1"}]]></xc:this.viewPanelName>
</xc:btn_ProcessDocuments>


Status Check. CC_Tickets should now look like this:
 Since the labels are computed they don’t show at design time but will render
correctly


Set the Combo box to filter the view
 Select the View
 All Properties - data - data “keys”
– This property allows filtering on a value. We will use the viewScope value “vsStatus” that
we created on page load and also bound the combo box to.

return viewScope.get("vsStatus")


Summary
 Created a custom control to show/edit Tickets
– Used a viewScope variable to set some defaults
– Used formTable and formRow to display the fields and labels
– Added a tool tip
– Added buttons to save and edit and close the ticket
 Created a custom control to view tickets
– Used the View control
 Created a Script Library to hold 3 SSJS functions
 Created a custom control for a button
– Allows Passing parameters in at runtime via properties
– compositeData object


Next
 Add the Ticket and Tickets custom controls to XPages
 Add to Navigation
 Create Additional supporting Pages


Create Ticket XPage
 XPages - New XPage. Name the XPage “ticket”. Click OK.


Drag the Controls for the ticket XPage
 Drag the layout_Main custom control onto the page
 Drag the cc_ticket control into the middle facet target


Drag the Controls for the ticket XPage
 The Source Pane will look like this. Save and Close


Create Tickets View XPage
 Just like creating the “ticket” XPage, create one for “tickets”
 XPages - New XPage
 Title the XPage “tickets”
 Drag the layout_Main onto the page
 Drag the cc_tickets custom control onto the middle facet target
 Save and Close


Test
 Open the tickets XPage
 Open the ticket XPage

 Preview both in browser


Create a New Ticket via a Button on Placebar
 Open the “layout_Main” custom control to edit
 Click on the Application Layout to select it in the Properties panel
 Click on the Place Bar tab, click Add Item, and select “Page Link Node”


Create a New Ticket via a Button on Placebar...
 Open the “layout_Main” custom control to edit
 Click on the Application Layout to select it in the Properties panel
 Click on the Place Bar tab, click Add Item, and select “Page Link Node”
 Fill in the label field and select the “ticket” page to open


 Hide the button when the user is on the Ticket page
 Click the empty blue diamond next to “rendered” and select “Compute value...”


 Enter the following Server Side Javascript and click OK
– This will display the button only if the user is on the ticket.xsp XPage

var url = context.getUrl();
if(@Contains(url, "ticket.xsp") == true) {
return false;
} else {
return true;
} © 2013 IBM Corporation © 2013 RunningNotes
134

Nav Bar...
 Create new CC called layout_Nav to hold the applications navigation menu


Nav Bar...
 Drag Navigator into Design Page


Adding Home to the Nav Bar
 Go to properties for the navigator
 Navigation Items - Click Add Item - Choose Page Link Node
 Set Label to Home and chose home in the page dropdown


Adding Tickets to the Nav Bar
 Go to properties for the navigator
 Navigation Items - Click Add Item - Choose Page Link Node
 Set Label to Tickets and chose tickets in the page dropdown


Add the Nav Bar to the layout
 Open the custom control created earlier, “layout_Main”
 Drag the custom control just created (“layout_Nav”) and drag it into the left-hand
target of the main layout


Test
 New Ticket Button
 Navigator


Create a Keywords “form”
 Create the custom control for the “form”
 Custom control - New Custom Control - Name it “cc_keyword_form”
 Click on the “Data” tab
 Add the keyword form as the data source


Create a Keywords “form”...
 Select the two fields and drag them onto the control
 Select the “Add Submit button to generated code” option


Get the viewScope to Know Which Document to Open
 Click on the data tab
 Change the default action to “Edit document”
 Input viewScope.get(“selectedKeyword”) into the editor
– This will hold the UNID of the keywords document we will be editing


Create a Keywords “View”
 Create the custom control for the “view”
 Custom controls - New Custom Control -
“cc_keyword_view”
 Drag the Container Control “View” onto
the Design pane
 The Select Data Source for View dialog
appears, use the “vwKeywords” view for
the source


Create a Keywords “View”...
 Click on the first column to select it
 Click on the events tab
 In the server side script editor for the on click event, enter
– viewScope.put("selectedKeyword",rowData.getUniversalID());
– This sets the viewScope used by the “form”


Create a Keywords XPage for form and view together
 Setting the viewScope on the “view” when the user clicks a row allows the “form” to
know which document to open for editing on the page
– Set the viewScope with the doc ID of the selected row
– Get the doc ID from the viewScope
– Have the form use the doc ID to know which doc to edit


Create a Keywords XPage for form and view together...
 Create the keywords XPage
 XPages - New XPage - named “admin”


 Drag the “layout_Main” control onto the page
 Drag a panel container control into the middle facet


 Drag the “cc_keywords_form” and “cc_keywords_view” controls into the panel


 Use the Outline to organize elements


Adding the Home Tab for Navigation
 Open the “layout_Main” custom control
 Click on the Title Bar tab
 Click Add Item, choose a Page Link node
 Change the label to “Home” and select the home page from the dropdown for page


Adding the Keywords Tab
 Repeat those steps to add another page link node
 Call it “Admin” and select the admin page for the page
 You now have a different way of navigating the application
 You can set the “render” property to hide the Admin tab if appropriate


CRUD
 At this point, we can:
– Create tickets (placebar button)
– Read tickets (tickets view)
– Update tickets (ticket custom control)
– Delete (custom control button)


Agenda
 Who We Are


Refining the Application
 Adding Comments via Repeat Control
 Validation
 Mobile


Adding a Repeat Control
 A Repeat Control an Iterate of any Multiple Value Element
– Notes View
– Multi-Value Field
– Array
– Vector
– Map
 Unlink View Control and Data Table there is no display markup built in
 You can make it look any way you want!


Adding a Repeat Control
 Create a new Custom Control
– Name: “cc_CommentView”
– Data source: Domino View, “vwCommentsByKey”
 Add a panel to the control
 Drag a Repeat Control into the panel


Binding the Repeat Control
 Give the collection a name: “commentData”
– This is allows us to reference the current row of data and do something with it
 Bind the repeat control:
var cView:NotesView = database.getView("vwCommentsByKey");
var vec:ViewEntryCollection = cView.getAllEntriesByKey
(compositeData.ticketKey, true)
return vec

 This creates the collection of entries that our repeat control will use


Displaying the Repeat Control
 Drag a table into the Repeat Control
– 1 row, 4 columns: 3 computed fields in the 2nd, 3rd, and 4th cell
 Into the first cell, drag another table
– 2 rows, 2 columns: 2 labels in top row, “Hours” & “Minutes”; 2 computed fields in bottom
row


Markup for the Table
<xp:table>
<xp:tr>
<xp:td>
<xp:table>
<xp:tr>
<xp:td>
<xp:label value="Hours" id="label1">
</xp:label>
</xp:td>
<xp:td>
<xp:label value="Minutes" id="label2">
</xp:label>
</xp:td>
</xp:tr>
<xp:tr>
<xp:td>
</xp:td>
<xp:td>
</xp:td>
</xp:tr>
</xp:table>
</xp:td>
<xp:td></xp:td>
<xp:td></xp:td>
<xp:td></xp:td>
</xp:tr>
</xp:table>

Adding Fields to the Repeat Control
 Now the cool part!
 Add a computed field to the cell below “Hours”
 Bind the data:
– commentData.getColumnValues()[4]
 This uses the collection created when we bound the repeat control as our “view”,
binding this computed field to the column value and displaying it inside the repeat
control will automagically display each “record” once in a panel, repeated on the
page
 Add the rest of the computed fields and bind them per the script snippet


Looking at the Repeat Control
This

Becomes this


Validation
 Validation can be found in two different places on a control, depending on the type
of control.


Validation
 Click on the Ticket Caller edit box.
 Simple validation can be added on the Validation tab.
 Select the check box next to “Required field”.
 Enter “Enter a ticket caller” for the error message.


Validation
 Select the Ticket Priority field
 On the All Properties tab, click the plus sign next to “validators”
 Select “xp:validateRequired”


Validation
 Click the dropdown next to “loaded” and select “true”
 Enter the message “Select a ticket priority” in the message field


Validation
 The previous steps are all that is needed for validation
 However, we can improve validation by adding nicer error messages
 Drag the Display Error control to the ticketCaller row
 In the Display Error tab select the ticketCaller field to “Show error messages for”
 Repeat for other rows with field validation


Validation
 In order for the Display Error controls to work, client side validation needs to be
disabled
 Go to Application Properties, XPages tab
 Select “Off” for Client Validation


Validation
 By default this will create table errors and row errors, in addition to the error
message control
 Click on the Form Table control, go to All Properties and set “disableErrorSummary”
and “disableRowError” to “true”


File Upload
 Add another Form Layout Row, label it “File Upload”
 Drag the “File Upload” control onto the custom control and bind the field to the
“ticketFiles” field


File Upload
 The Source pane for the file upload control


File Download
 Create another form row
 Drag the File Download control onto the row
 Make the following selections


Mobile Applications
 Mobile Applications are considered Single Page Applications
– Only 1 XPage is used
– You create Virtual Pages inside a Single Page Application Container
– You can control how the transitions between virtual pages occur with “moveTo”
• moveTo is a common property on most mobile controls
• Also a simple action


Mobile
 Create a new XPage called “m_home”
 Drag the “Single Page Application” control from the Mobile menu onto the page


Mobile
 Go to the All Properties tab of the Single Page Application control
 Give it an id of “mobileApp” and the selectedPageName as “mobileHome”
 These are important for “Back” actions and “page” navigation


Mobile
 Drag the “Mobile Page” control onto the Singe Page Application
 Give it an id of “mobileHome1”, pageName of “mobileHome”, and resetContent to
“false”


Mobile
 Drag the Page Heading control onto the Mobile Page control
 Set the id to “mobileHeading” and the label to “Home”


Mobile
 At this point, each of the items should be nested within each other


Mobile
 Next drag the Rounded List onto the Mobile Page
– NOT inside the page heading control


Mobile
 Next drag the Static Line Item into the Rounded List
 Change the label to “Open Tickets” and the moveTo to “#viewPage”
 This will create a list item that will open to the “page” we call “viewPage”


Mobile
 Drag another Mobile Page onto the Single Page Application control
– NOT inside the prior mobile page control
 Edit the id to “appPage1”, pageName to “viewPage”, preload to “true” and
resetContent to “true”


Mobile
 Drag a new Page Heading control onto the just created Mobile Page
 Change the back to “Back”, label “Open Tickets”, and moveTo to “#mobileHome”
– This creates a heading that when clicked will go back to our mobile home “page”


Mobile
 Drag a Data View control onto the “appPage1” Mobile Page control
 Make the appropriate changes so your source looks like this
 This creates a view control with “vwTicketsByStatus” as the source, but only
displays “Open” tickets (keys=”Open”)
 Clicking Back will take the user to the mobileHome “page”


One more mobile page and we’re done
 Drag another mobile page onto the Single Page Application control
– Make id “appPage2” and pageName “documentPage”
 Drag a new heading onto the mobile page
– Make back “Back” and moveTo to “#viewPage”


One more mobile page and we’re done
 Drag a panel onto the mobile page
– Add the ticket form as the data source, called document1
 Drag a rounded list onto the panel
 Add four labels and four edit boxes
 Change the data source for the four edit boxes to: ticketKey, ticketDate, ticketCaller
and ticketDescription from document1


Mobile Redirect Page
 Create a new XPage, call it “main”
 Put the following in the source pane
 This will check to see how the user is contacting the page and redirect to the
mobile page, if appropriate. Otherwise, the user will be directed to the regular
page.
 This allows a single URL and launch page to be set for the application
 <?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:this.afterPageLoad>
<![CDATA[#{javascript:
var uAgent = context.getUserAgent().getUserAgent();
if ((uAgent.match("iPhone") !== null || param.platfrom=="iphone") || (uAgent.match("Android") !== null ||
param.platfrom=="android") || uAgent.match("iPad") !== null)
{
context.redirectToPage("/m_home.xsp", true);
}
else
{
context.redirectToPage("/home.xsp", true);
}
}]]>
</xp:this.afterPageLoad>
</xp:view>


Mobile Application Properties
 Open the package explorer
 Go to WebContent, WEB-INF and open xsp.properties
 Add the line “xsp.theme.mobile.pagePrefix=m”
 Save and close


Reference
 Suggested sessions
– AD204 : How To Develop Great Applications Using XPages Design Patterns
– AD202 : Debug Server Side Javascript, Java, and XPages Apps Using the SSJS
Debugger
– BP208 : XPages Blast
– BP202 : XPages Development: Modernize Yourself!
– BP206 : It's Not Herculean: Twelve Tasks Made Easier With IBM Lotus Domino XPages
– BP103 : jQuery: The World's Most Popular JavaScript Library Comes to XPages
– Many Many more....
 Useful links
– XPages.info
– OpenNTF.org
• http://openntf.org/XSnippets.nsf
– notesin9.com
– XPagesWiki.com
– http://www-10.lotus.com/ldd/xpagesforum.nsf
– http://stackoverflow.com/questions/tagged/xpages
– Mobile Controls tutorial - http://www-10.lotus.com/ldd/ddwiki.nsf/dx/
XPages_Mobile_Controls_Tutorial_


Questions?

Kathy Brown - kbrown@psclistens.com - @runningnotes
David Leedy - dleedy@notesin9.com - @DavidLeedy


Legal disclaimer
 © IBM Corporation 2013. All Rights Reserved.
 The information contained in this publication is provided for informational purposes only. While efforts were made to
verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without
warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and
strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising
out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this
publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its
suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of
IBM software.
 References in this presentation to IBM products, programs, or services do not imply that they will be available in all
countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may
change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to
be a commitment to future product or feature availability in any way. Nothing contained in these materials is
intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any
specific sales, revenue growth or other results.


XPages: No Experience Needed

More Related Content

What's hot

Similar to XPages: No Experience Needed

More from Kathy Brown

Recently uploaded

XPages: No Experience Needed