xpages: no experience needed

© 2013 IBM Corporation © 2013 RunningNotes

SHOW 111 XPages: No Experience NeededKathy Brown | ConsultantDavid Leedy | Collaborative Solutions Developer

© 2013 IBM Corporation © 2013 RunningNotes2

Agenda Who We Are

What We Are Building

What Are XPages?

Creating the Application

Refining the Application


Who We Are Kathy Brown

– Consultant at PSC Group, LLC• www.psclistens.com• @pscgroup• [email protected]

– 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

http://www.psclistens.com

http://www.psclistens.com

mailto:[email protected]


http://www.runningnotes.net

http://www.runningnotes.net


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• [email protected]




IBM TrademarksDomino®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

5




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

9


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

10


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

11


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

12


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...

13


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

14


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

15

http://notesin9.com

http://notesin9.com

http://runningnotes.net

http://runningnotes.net

http://extlib.openntf.org/

http://extlib.openntf.org/


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 files\lotus\notes\data

16


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

17


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

18


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”

19


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.

20


Open the Starter application from Domino Designer

21


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

22


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

23


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

24


Opening from ServerFinally open the server version just like we did the local

25


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

26


Agenda Who We Are

XPages


What 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

28


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)

29


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

30

* 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”

31


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

32


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

33


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

34


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.

35


Create ability to Login / Logout Select the App layout control that you dropped on the page

Add Login and Logout Node*

36

*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

37


Login/Logout Workaround Before we create logout - Display the current user name

Create another node, a User Node

38


Showing current user

39

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 uservar userName:NotesName = session.createName(session.getEffectiveUserName());// If the user is not Anonymous then return a welcome messageif (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

40


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

41

return facesContext.getExternalContext().getRequest().getContextPath() + "?Logout&redirectTo=" + facesContext.getExternalContext().getRequest().getContextPath()

href property computed value:


Adding Logout Fix– Compute the rendered property

• This returns true (Logout node is visible) if the user is logged in, ie not Anonymous

42

var uName = session.getEffectiveUserName();if (uName == "Anonymous") { return false; } else { return true; }

rendered property computed value:


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.

43


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

44


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

45


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

46


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

47


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

48


Set the Launch - Go back to Application Properties

49

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

50

* 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

51


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

52


Next Up Create Custom Control for the Help Ticket

Create Custom control to View tickets

Create a Custom Control for the Navigation menu list

53


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

54


Create Data Binding

55

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...

56

select form_ticket and name the data source ticketDoc


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

57

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


Add This code from Script Snippets

58

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

59

<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)

60


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

61


Add Title to Form Table Select the Form table

Add the formDescription and formTitle

62


Drag form layout row onto form layout table body’s green dot

63

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”)

64


Check the Source

65


Set up the first form layout row Set Label to “TicketID”

Drag Computed Field to right most Green Dot

66


Bind computed Field to “ticketKey” field

67

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

68

<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>

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.


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”

69

<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

70


Add the Caller name field

71

<xe:formRow id="formRow3" label="Caller" labelPosition="inherit"> <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>

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


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

72


Add Ticket Category This is a combo box. Note there is Server Side JavaScript Code for looking up the

values

73

<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 selectionvar 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:

74


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

75


Now add the row for Platform

76

<xe:formRow id="formRow7" label="Platform" labelPosition="inherit" 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 selectionvar mychoices = new Array("");var mydb = new Array(database.getServer(),database.getFilePath());var myotherchoices = @DbLookup(mydb, "vwKeywords", "platform", 2);var mytotalchoices = mychoices.concat(myotherchoices);return mytotalchoices;}]]></xp:this.value> </xp:selectItems> </xp:comboBox></xe:formRow>

Note the change in value for each field, and different keyword in the DbLookup


Now add the row for Priority

77

<xe:formRow id="formRow7" label="Priority" labelPosition="inherit" for="platform1"> <xp:comboBox id="platform1" value="#{ticketDoc.ticketPriority}"> <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 selectionvar mychoices = new Array("");var mydb = new Array(database.getServer(),database.getFilePath());var myotherchoices = @DbLookup(mydb, "vwKeywords", "priority", 2);var mytotalchoices = mychoices.concat(myotherchoices);return mytotalchoices;}]]></xp:this.value> </xp:selectItems> </xp:comboBox></xe:formRow>



Now add the row for Status

78

<xe:formRow id="formRow7" label="Status" labelPosition="inherit" for="platform1"> <xp:comboBox id="platform1" value="#{ticketDoc.ticketStatus}"> <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 selectionvar mychoices = new Array("");var mydb = new Array(database.getServer(),database.getFilePath());var myotherchoices = @DbLookup(mydb, "vwKeywords", "status", 2);var mytotalchoices = mychoices.concat(myotherchoices);return mytotalchoices;}]]></xp:this.value> </xp:selectItems> </xp:comboBox></xe:formRow>



Add A Default Value for the Status ComboBox

79

Select the status field

On the Data tab, enter “Open” for the default value


Add the Description Row

80

<xe:formRow id="formRow5" label="Description" labelPosition="inherit"> <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:

81


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

82


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

83


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

84

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

85


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

86

// Hide button if it's in save modereturn 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”

87


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

88

<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

89

<xp:buttonvalue="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" refreshMode="complete"> <xp:this.action> <xp:changeDocumentMode mode="edit" var="ticketDoc">

</xp:changeDocumentMode> </xp:this.action> </xp:eventHandler></xp:button>

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


Forcing a Space After each button tag add

This forces a space

90

</xp:button>


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

91


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

92


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”.

93


Drag a Panel onto the page. – Give it the id of “statusPanel”– Could also be added directly in source after the beforePageLoad tag

94

<xp:panel id="statusPanel"> </xp:panel>

Add A Panel To Select Type of Tickets


Inside the Panel add a Combobox

95

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

96

<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

97


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

98


Add a Checkbox to the first column Select the first column

Display Tab - select “Check box” - then Save the custom control

99


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

100


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

101


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

Save and close

102


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

103

.oddRow { BACKGROUND-COLOR: RGB(248, 248, 248);}.oddRow:HOVER { BACKGROUND-COLOR: RGB(98, 120, 150);color: #FFFFFF;font-weight:bold;}.evenRow:HOVER { BACKGROUND-COLOR: RGB(98, 120, 150);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

104


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

105


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

106


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

107


Add Function for getSelected

108

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 }

This function will return an array with the selected documents’ IDs


Add function for processDocuments

109

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

110

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 first 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:

111


Save Script Library and exit XPages and Custom Controls can access Script Libraries as resources. We will

add it to the control later.

112


Create button custom control New Custom Control

call it btn_ProcessDocuments

113


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

114


Adding a Script Library In the Resources tab, click “Add” and select “Javascript Library”

Then select the SSJS Utilities javascript library

115

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


Add a button to the control

116

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

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


Finishing the button

117

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

In the “onclick” event call code in the script library to process documents

Save and Close


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

118


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

119


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

120


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> <xc:btn_ProcessDocuments action="Waiting" buttonName="Set to Waiting" viewPanelName="viewPanel1"></xc:btn_ProcessDocuments> <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:

122

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.

123

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

124


Next Add the Ticket and Tickets custom controls to XPages

Add to Navigation

Create Additional supporting Pages

125


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

126


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

127


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

128


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

129


Test Open the tickets XPage

Open the ticket XPage

Preview both in browser

130


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”

131


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

132


Create a New Ticket via a Button on Placebar... Hide the button when the user is on the Ticket page

Click the empty blue diamond next to “rendered” and select “Compute value...”

133


Create a New Ticket via a Button on Placebar... Enter the following Server Side Javascript and click OK

– This will display the button only if the user is on the ticket.xsp XPage

134

var url = context.getUrl();if(@Contains(url, "ticket.xsp") == true) { return false;} else { return true;}


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

135


Nav Bar... Drag Navigator into Design Page

136


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

137


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

138


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

139


Test New Ticket Button

Navigator

140


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

141


Create a Keywords “form”... Select the two fields and drag them onto the control

Select the “Add Submit button to generated code” option

142


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

143


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

144


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”

145


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

146


Create a Keywords XPage for form and view together... Create the keywords XPage

XPages - New XPage - named “admin”

147


Create a Keywords XPage for form and view together... Drag the “layout_Main” control onto the page

Drag a panel container control into the middle facet

148


Create a Keywords XPage for form and view together... Drag the “cc_keywords_form” and “cc_keywords_view” controls into the panel

149


Create a Keywords XPage for form and view together... Use the Outline to organize elements

150


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

151


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

152


CRUD At this point, we can:

– Create tickets (placebar button)– Read tickets (tickets view)– Update tickets (ticket custom control)– Delete (custom control button)

153


Agenda Who We Are


What Are XPages?




Refining the Application Adding Comments via Repeat Control

Validation

Mobile

155


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!

156


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

157


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:

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

158

var cView:NotesView = database.getView("vwCommentsByKey");var vec:ViewEntryCollection = cView.getAllEntriesByKey(compositeData.ticketKey, true)return vec


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

159


Markup for the Table

160

<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

161


Looking at the Repeat Control

162

Becomes this

This


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

of control.

163


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.

164


Validation Select the Ticket Priority field

On the All Properties tab, click the plus sign next to “validators”

Select “xp:validateRequired”

165


Validation Click the dropdown next to “loaded” and select “true”

Enter the message “Select a ticket priority” in the message field

166


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

167


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

168


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”

169


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

170


File Upload The Source pane for the file upload control

171


File Download Create another form row

Drag the File Download control onto the row

Make the following selections

172


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

173


Mobile Create a new XPage called “m_home”

Drag the “Single Page Application” control from the Mobile menu onto the page

174


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

175


Mobile Drag the “Mobile Page” control onto the Singe Page Application

Give it an id of “mobileHome1”, pageName of “mobileHome”, and resetContent to “false”

176


Mobile Drag the Page Heading control onto the Mobile Page control

Set the id to “mobileHeading” and the label to “Home”

177


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

178


Mobile Next drag the Rounded List onto the Mobile Page

– NOT inside the page heading control

179


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”

180


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”

181


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”

182


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”

183


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”

184


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

185


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>

186

http://www.ibm.com/xsp/core

http://www.ibm.com/xsp/core


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

187


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_

188

http://openntf.org/XSnippets.nsf

http://openntf.org/XSnippets.nsf

http://www-10.lotus.com/ldd/xpagesforum.nsf

http://www-10.lotus.com/ldd/xpagesforum.nsf

http://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_Mobile_Controls_Tutorial_





Questions?

189

Kathy Brown - [email protected] - @runningnotes

David Leedy - [email protected] - @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

Technology

ibm corporation

xpages apps

xpages fix

java server faces xpages

notes client xpinc xpages

java objects beans

hours of free xpages

java beans