Xpages

Mastering #XPages: Buy the eBook

I’ve had my copy of Mastering XPages (2nd Edition) for a little while. It’s a darn heavy book, but because of that, it’s packed with information. More packed that the 1st Edition? Why, yes, yes it is. Mine is in hard cover and the 1100-plus pages is a little bit daunting to carry around. Nonetheless, there is nothing quite like it.

I’ve always been a guy who learns well from physical books. I like the feel of them. I like the structured approach to learning that they provide. The code examples in the text, along with great images, really provide a lot on insight to what you can do with XPages. I’d say it compares well with reading a variety of blogs because of the depth and structure provided. I can and do read dozens of blogs, but they don’t have any comprehensive structure. For example, I write mostly about the problems that I’ve encountered coding in XPages. While that might teach you a lot about XPages, it’s got no structure at all. If you read Marky’s blog, you’ll learn a lot, and often in a structured manner about the topic he’s dealing with, but it won’t take you from ground zero to XPages developer. Similarly, the extensive XPages library over at Notes in 9 is fantastic (and you ought to be watching all of those videos), but there’s not necessarily a comprehensive plan, nor a logical learning order. I love Paul Della-Nebbia’s video series, Intro to XPages, as it’s a great place to start learning, but you won’t get 21 chapters of knowledge there.

Now, before you start thinking it’s a massive slog of text with only hard-copy code samples, brace yourself. Just like the blogs noted above, you can download sample applications that go along with the examples in the book to help you learn all aspects of XPages.

In the months I’ve owned it, I’ve read several chapters straight through, used one chapter (18 – Internationalization) to add a huge capability to our applications with a mere hour of research and searched through the massive text for little bits and pieces.

This brings me to the electronic version. I’m old. I’ve admitted above to loving books. As I was pondering my review, I thought I needed to try the electronic version. So, using the code supplied in the hard-copy of the book, I added the electronic version to my tablet (Motorola Xoom that’s getting a bit long-in-the-tooth). I searched a little, which definitely beats the heck out of the hard copy’s index, since you can not only find more, but also jump directly to that spot in the text. I sat and read a little — I’ve already established that I’m willing to read books on it with military history — and it’s very nice. When you get into books over a thousand pages, it’s so much easier to tote around an electronic copy in your backpack, or read on the Metro, or pluck it out of your carry-on while flying to MWLUG. I highly recommend the electronic version. Depending on finances, I might not worry about the hard copy next time and simply get my hands on the e-book.

This edition adds in various changes from the release of the 1st edition — over 3 years of changes. It’s written in the irrepressible style that won Marky’s approval. It’s a jam-packed learning experience. If you don’t have it already, do yourself a favor and get a copy today. Try the electronic version. You’ll thank me.

Categories: Xpages | Tags: , , , , , , | 3 Comments

MWLUG 2014 video series on Youtube

I took along my videocamera to MWLUG 2014 in Grand Rapids and I’ve created a playlist of the videos that I’ve already uploaded to Youtube. Since I’m a developer, it leans heavily on development sessions.

As more are added, they will appear there and here….

The playlist includes the following videos thus far:

AD104: Build A Bean Workshop – Devin Olson and Mike McGarel

BP107 Java versus Javascript: There really is no competition – Andrew Barickman

AD101: Achieving Developer Nirvana With Codename BlueMix – Ryan Baxter

AD105: Building a Structured App With XPages Scaffolding – Jesse Gallagher

Bonus track: WWII veteran Virgil Westdale in the Opening General Session

Other sessions are waiting on some approvals from the speakers and some editing (one session had live data displayed, so I have to edit that out)

These only give an impression of the event. You get an awful lot more out of it if you attend. So, see you in Atlanta next year!

Categories: Conferences, Java, Videos, Xpages | Tags: , , , , , , , | 2 Comments

Exception avoided in FTSearchSorted in #XPages

Regular readers will remember that I’ve been playing around with using FTSearchSorted in order to create Excel spreadsheets from Notes databases in XPages. I’d had that in my sample database for a while, but hadn’t used it our production environment yet. I worried that my experience with crashes was going to be repeated and that it would take forever to integrate it into the design. Fortunately, I got over my concern about crashes (that’s what an admin team is for, right?) since my coding and the versioning all make it seem stable. The integration of the changes (modify one form, one button on a custom control and a few lines in a script library) was relatively quick. So, in the spirit of the 442nd, I decided to “Go For Broke”.

Having pushed the changes to my development environment, I set up a new report with a querystring and a sort column. My brilliant code would soon return a report of all contacts with their city = “Bethesda”, sorted by… Position since that was a column in the view and I was being random. It didn’t work. I played around with the querystring and finally decided to use FTSearch without using sort or my sort column. That worked. So, I tried FTSearchSorted, with the column name in parentheses, so it would definitely be string. Then, a number for the column instead. Then, I decided, I wouldn’t provide a sort column at all. That worked. So it wasn’t the method and it wasn’t the values I was passing to it. It just returned a silly null object every time.

So, I turned to Stack Overflow. Sure enough, someone else had the problem. The answer provided (too short in the Stack Overflow admins’ minds) was from Thomas Adrian, “make sure the view is user sortable”. Aha! I went back to my form, on which I had placed useful help text that I didn’t bother to read:

A column may only be used for sorting if it has been designed to allow “Click on column header to sort” on the Sorting tab of the column properties. The relevant options are Ascending, Descending, and Both. Trying to sort a column in an unsupported direction throws an exception.

I even bolded the important part of the text on my form. I hadn’t read it when I picked my sort column, so it threw an exception every time I used one of those unsorted columns.

Since I’ve demonstrated that even I won’t read my help text, I’ve changed the code on the button that allows you to select which column to use as your sort column so that you can’t choose one that isn’t sorted either ascending or descending. It will only list choices that are click to sort one way or the other (or both).

Forall columns In columnArray
	If ( columns.Isresortascending Or columns.Isresortdescending ) Then
		' add each view name to an array if it is eligible for click to sort
		Redim Preserve headerArray ( count )
		headerArray ( count ) = columns.ItemName
		Print headerArray ( count )
		count = count + 1
	End If
End Forall

I’ve added a clearer explanation to Thomas’ answer, but that short sentence was all the answer I needed. Once my expansion of his answer clears the editors, it will look nicer up there, but since you’ve already read this blog post, you won’t need it, eh?

I’ve updated the sample database, so you can download it to see the rest of how it works if the code sample is not enough. I’ll be at MWLUG starting tomorrow afternoon, so make sure to say “Hello”!

Categories: Server-Side Javascript, Xpages | Tags: , , , , , , , | Leave a comment

Simple dialog returning a value to your #XPages

Since I’m still new to XPages, I’m always finding things that are a challenge. Most of the time, I don’t know how big a challenge they are because doing things in XPages isn’t the same as doing them in Old Notes.

Business case

On the payment request in our procurement module, the user needs to enter the exchange rate between the local currency and the base currency for approval routing. Sometimes, the payment has already been made in local currency while the exchange rate has changed. They might only know the amounts in the two currencies, but didn’t record the exchange rate at the time.

PaymentRequest

Solution

In discussions, I suggested that it might not be difficult to simply have a popup that allowed the user to enter the amounts and return the value to the payment request in the UI.

Surprisingly to me, I was right. It’s not that hard. My challenge was that I decide to put this exchange rate computer into a custom control so that I’d be able to re-use it. That meant having to figure out how to have the dialog do a partial refresh on the payment request, in order to recompute the total amount in the base currency (USD).

Existing design considerations

Our procurement module was originally designed by the brilliant minds over at Teamwork Solutions, led by Scott Good. It’s very nice, but this wasn’t included in the original requirements gathering. (What percentage of actual requirements do get into the original requirements gathering?)

Each of those line items displayed in the payment request is a separate Notes document, so, in Old Notes terms, this would be like an embedded view, but since we’re in XPages, it’s a repeat. (I am learning to love repeats!) The total payable amounts are ‘computed fields’ in XPages, which is like a computed for display field in Old Notes. As such, they wouldn’t actually save anything to the payment request document. So, we have some non-displayed computed fields with some server-side Javsacript (SSJS) that aggregates all the local amounts from those view entries and puts it into the control on the XPage. As such, when the exchange rate changes, there is a partial refresh.

So, on our exchange rate control, we had a partial refresh for onchange. Simple control, bound to a field on our payment request document.

<xp:inputText id="exchangeRate" value="#{payDoc.Exchange_Rate}" style="text-align:right;width:70.0px;">
	<xp:this.converter>
		<xp:convertNumber type="number"></xp:convertNumber>
	</xp:this.converter>
	<xp:eventHandler event="onchange" submit="true" refreshMode="partial" refreshId="paymentCostInfoPanel">
	</xp:eventHandler>
</xp:inputText>

Design

So, I created my exchangeRateComputer custom control. I decided to make the link part of the custom control so that implementing it on any other XPage would require the least work possible.  I decided to always set the control on the XPage to be named “exchangeRate”, so I don’t have to pass a string with the control name. As an added bonus, I wanted to fill out the local currency field for the user and just let them enter the final base currency amount they’d like to see.

ExchangeRateCalculator

I ran into one problem. I couldn’t get it to do the partial refresh from the exchangeRateComputer custom control. I’d tried some XSP.partialRefreshGet commands but was having problems and realized…. I might want the name of the element to be refreshed to be different on different XPages. Since passing the compositeData value into the XSP.getElementById seemed beyond my capabilities, I decided to simply defer all refreshes to the exchangeRate control itself. So, I ended up adding an onblur partial refresh. When the user clicks on the ‘Apply to payment request button’, it puts focus onto the exchangeRate control, then, closes the dialog. Closing the dialog blurs focus from the exchangeRate control and…. with an added onblur event, performs a partial refresh for me. (The onblur event is identical to the onchange, except for the name.)

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core" xmlns:xe="http://www.ibm.com/xsp/coreex">
	<xp:link escape="true" text="Compute Exchange Rate" id="computeLink" 
		style="margin-left:5px;">
		<xp:eventHandler event="onclick" submit="false">
			<xp:this.script><![CDATA[XSP.openDialog('#{id:computeDialog}');]]></xp:this.script>
		</xp:eventHandler>
	</xp:link>

	<xe:dialog id="computeDialog" title="Exchange rate calculator">
		<xp:table>
			<xp:tr>
				<xp:td>
				</xp:td>
				<xp:td>
					<xp:label id="instructions" value="Enter the amounts below to calculate an exchange rate">
					</xp:label>
				</xp:td>
			</xp:tr>
			<xp:tr>
				<xp:td style="width:150px;text-align:right;">
					<xp:label id="total_baseCurrencyLabel" value="Total Base Currency">
					</xp:label>
				</xp:td>
				<xp:td>
					<xp:inputText id="total_baseCurrency" style="width:100px;text-align:right;">
						<xp:this.converter>
							<xp:convertNumber type="number"></xp:convertNumber>
						</xp:this.converter>
						<xp:eventHandler event="onchange" submit="true"
							refreshMode="complete">
							<xp:this.action><![CDATA[#{javascript:var base = getComponent("total_baseCurrency").getValue();
var local = getComponent("total_localCurrency").getValue();
rate = local / base;
getComponent("rate").setValue(rate);}]]></xp:this.action>
						</xp:eventHandler>
					</xp:inputText>
				</xp:td>
			</xp:tr>
			<xp:tr>
				<xp:td style="text-align:right;">
					<xp:label id="total_localCurrencyLabel" value="Total Local Currency">
					</xp:label>
				</xp:td>
				<xp:td>
					<xp:inputText id="total_localCurrency"
						defaultValue="#{javascript:compositeData.localCurrency}"
						style="width:100px;text-align:right;">
						<xp:this.converter>
							<xp:convertNumber type="number"></xp:convertNumber>
						</xp:this.converter>
						<xp:this.validators>
							<xp:validateLongRange minimum="1"></xp:validateLongRange>
						</xp:this.validators>
						<xp:eventHandler event="onchange" submit="true"
							refreshMode="complete">
							<xp:this.action><![CDATA[#{javascript:var base = getComponent("total_baseCurrency").getValue();
var local = getComponent("total_localCurrency").getValue();
rate = local / base;
getComponent("rate").setValue(rate);}]]></xp:this.action>
						</xp:eventHandler>
					</xp:inputText>
				</xp:td>
			</xp:tr>
			<xp:tr>
				<xp:td style="text-align:right;">
					<xp:label id="rateLabel" value="Exchange Rate"></xp:label>
				</xp:td>
				<xp:td>
					<xp:text escape="true" id="rate"></xp:text>
				</xp:td>
			</xp:tr>
			<xp:tr>
				<xp:td>
				</xp:td>
				<xp:td>
					<xp:button value="Apply to payment request"
						id="copyButton">
						<xp:eventHandler event="onclick" submit="true"
							refreshMode="complete">
							<xp:this.script><![CDATA[var rate = XSP.getElementById("#{id:rate}"); 
XSP.getElementById("#{id:exchangeRate}").value = rate.innerHTML;
XSP.getElementById("#{id:exchangeRate}").focus();
XSP.closeDialog('#{id:computeDialog}');]]></xp:this.script>
						</xp:eventHandler>
					</xp:button>
					<xp:button value="Cancel" id="cancelButton">
						<xp:eventHandler event="onclick"
							submit="false">
							<xp:this.script><![CDATA[XSP.closeDialog('#{id:computeDialog}');]]></xp:this.script>
						</xp:eventHandler>
					</xp:button>
				</xp:td>
			</xp:tr>
		</xp:table>
	</xe:dialog>
</xp:view>

The last tweak to it is that my computed exchange rate in the dialog is just a computed field. I struggled a little until a dogpile search revealed that I needed to get that value as innerHTML. If you try getValue() on a computed field, you get bupkis, but if you grab the innerHTML, you’ve got the world in your hands.

It feels like that would be easier in Old Notes, but I hardly care any more. I have a new micro-solution in my toolbox and I expect to re-use this not only for other exchange rate computations, but to re-use the dialog and value-passing in many places. It’s all about building up your toolkit, right?

Categories: Client-Side Javascript, Old Notes, Server-Side Javascript, Xpages, XSP Functions | Tags: , , , , , , , , , , | 1 Comment

Exporting to Excel using Queries in #Xpages

In Paul Calhoun’s Jump Start presentation (JMP101) at IBM Connect, he was talking about using Apache POI for exporting data to Excel. I’d gotten interested when he spoke about this before, which led me to developing my own two-part posting on exporting data to Excel without having Excel (part 1, part 2). What intrigued me was his discussion of both selected documents and ad hoc queries of Notes views. My immediate thought was that I could enhance capabilty and avoid the creation of multiple new views by configuring new exports for the users via queries of our own. Once I have that working, I’ll look at allowing the users to select documents and then, perhaps, allow ad hoc queries entered by users. It’s not that I don’t want to provide the capability, I just want to be cautious about it.

In our implementation, I’ve got our development team configuring reports for the users in documents, with the end users having no real-time input into the contents of the report. The thing I’d most like to change is to move the document selection from the view selection formula into those configuration documents.

Writing a Query

The first hurdle that I have is that despite 20 years of Notes development experience, I’ve never written a full-text query. I don’t usually access databases as an end user, so it never really comes up for me. Way back in the day, when I was at Exxon-Mobil, there were some full-text indexes and queries, but as the most junior developer on the staff, I never needed to be involved in designing the interface for that or in explaining how it worked. So, here in 2014, I’ve got to learn the syntax so we can create some pre-configured queries for our users.

I found the search operators help document relatively easily. While I don’t know SQL queries either, I was hoping that it would use the same syntax so that learning this would be useful later, so that getting help from outside our community would be easy and so that people from outside (including my end users) would be able to use it easily as well. At first glance, I thought they were similar, with CAPITALIZED words and logical operators (AND, OR, etc), but the similarity ends very quickly. The Notes search query is not at all like SQL queries.

Operator
Description and examples
Where operator works
CONTAINScontains= Requires that the field before it must contain the text after it. There should be spaces between ‘CONTAINS’ and words surrounding it.Example

[Projectname] CONTAINS top secret

Finds documents whose Projectname field contains the words ‘top secret.’

Notes view – Yes
Notes domain – Yes
Web view/domain – No
IS PRESENT Requires that the field before it must be non-blank. There should be spaces between ‘IS PRESENT’ and words surrounding it. This operator can be used to find all documents that do (or do not) contain a value in a particular field.Example

[Subject] IS PRESENT

Finds documents whose Subject field is non-blank.

Notes view – Yes
Notes domain – Yes
Web view/domain – No
field fieldnameFIELD fieldname[fieldname] (use square brackets) Means ‘search this field.’ You must specify the field to search by using its field name.ExampleEach of the following are equivalent ways to find documents whose Projectname field contains the phrase top secret:

FIELD Projectname CONTAINS top secret

field Projectname CONTAINS top secret

[Projectname] CONTAINS top secret

Note Notes stores file attachments in the $FILE field.

Notes view – Yes
Notes domain – No
Web view/domain – Yes, but in view searches only
( ) [parentheses] Determines the order in which sections of your query are processed. A part of the query enclosed in parentheses will be processed before parts outside the parentheses.Example

(FIELD Projectname CONTAINS top secret OR FIELD Title CONTAINS tuna) AND (Field body CONTAINS cat OR Field revdate > 01/01/2004)

Return documents whose Projectname field contains the words ‘top secret’ or whose title field contains the word ‘tuna’; and either the body field contains the word cat or the revdate field contains a date greater than 01/01/2004.

Notes view – Yes
Notes domain – No
Web view/domain – Yes
andAND& Finds documents containing all the conditions or words linked by AND.Example

cat AND dog AND fish

Finds documents containing all three of these words.

Notes view – Yes
Notes domain – Yes
Web view/domain – Yes except ‘&’ does not work
orOR|ACCRUE, (comma) Finds documents containing either of the conditions or words and returns them ranked by number of appearances in the document.Example

cat OR dog OR fish

Finds documents containing at least one of these words.

Note ACCRUE works slightly better than OR when sorting results by relevance.

Notes view – Yes
Notes domain – Yes
Web view/domain – Yes
NOTnot! Excludes documents containing the term that appears after the operator.ExamplesYou can put NOT between words:

  • cat AND NOT dog
    Finds documents containing the word cat, but not if they also contain the word dog.
  • (cat OR dog) AND NOT (fish OR frogs)
    Finds documents containing the word cat or dog, but not if they also contain the word fish or frog.
  • (cat AND dog) AND NOT fish
    Finds documents containing the words cat and dog, but not if they also contain the word fish.

You can put NOT before any field name:

  • NOT [Projectname] CONTAINS top secret
    Finds documents whose Projectname field does not contain the words ‘top secret.’

You cannot put NOT after the math symbols =, <, >, <=, or >=; and before a date or number:

  • [date1] = NOT 12/25/2002
    is not an appropriate query.
Notes view – Yes
Notes domain – Yes
Web view/domain – Yes
” “ Requires that only documents containing the exact phrase are returned. Placing double quotes around operators (like AND, OR, CONTAINS etc.) allows them to be read as normal words.Example

“rock and roll”

Finds documents containing the phrase rock and roll.

Notes view – Yes
Notes domain – Yes
Web view/domain – Yes
PARAGRAPHparagraph Finds documents in which the words surrounding PARAGRAPH are in the same paragraph, and ranks them by how close they are.Example

car PARAGRAPH wheels

Finds documents in which ‘car’ and ‘wheels’ appear in the same paragraph and ranks them by how close the words are within the paragraph.

Notes view – Yes(If the application’s full-text index has been created with the “Index sentence and paragraph breaks” option selected. For more information, see Full-text index options.)
Notes domain – Yes
Web view/domain – No
SENTENCEsentence Finds documents in which the words surrounding SENTENCE are in the same sentence, and ranks them by how close they are.Example

car SENTENCE wheels

Finds documents in which ‘car’ and ‘wheels’ appear in the same sentence and ranks them by how close the words are within the sentence.

Notes view – Yes(If the application’s full-text index has been created with the “Index sentence and paragraph breaks” option selected. For more information, see Full-text index options.)Notes domain – Yes
Web view/domain – No
? A wildcard that can represent any single letter. It does not work with dates or numbers.Examples

?one

Finds documents containing bone, cone, done, gone (and any other four-letter words that end with ‘one’)

???ck

Finds documents containing stack, clock, stick, truck; rack, rick, rock

Notes view -Yes
Notes domain – Yes
Web view/domain – Yes
* A wildcard that can represent any extension of letters. It does not work with dates or numbers.Examples

*one

Finds documents containing bone, cone, clone, crone, done, drone, gone, telephone (and any other words of any length that end with ‘one’).

Also,

*one*

Finds documents containing bone, cone, clone, lonely, phoned, stoned, pardoned.

Notes view – Yes
Notes domain – Yes
Web view/domain – Yes
TERMWEIGHTtermweight Gives importance, or “weight,” to search words. You can use any value from 0 through 65537 to assign weight.Example

TERMWEIGHT 25 photo or TERMWEIGHT 75 audio or TERMWEIGHT 50 video

Finds documents containing at least one of the words. ‘Audio’ is most important, ‘video’ is next, and ‘photo’ is least important. Notes ranks results accordingly. You need an AND or OR between first TERMWEIGHT and subsequent ones.

Notes view – Yes
Notes domain – Yes
Web view/domain – No
EXACTCASEexactcase Search for the exact case of the word sepcified after the operator.Example

exactcase Apple

Finds documents containing ‘Apple,’ but not ‘APPLE’ or ‘apple.’

Notes view – Yes(If the application’s full-text index has been created with the “Enabled case sensitive searches” option selected. For more information, see Full-text index options.)Notes domain – NoWeb view/domain – No
= (equal)< (less than)> (greater than)<= (less than or equal)>= (greater than or equal) Search for numbers or dates in numeric or date fields only.Example

FIELD date1<12/25/98

Finds documents whose ‘date1’ field contains any date before 12/25/98.

Notes view – Yes
Notes domain – Yes
Web view/domain – No
– (hyphen) Finds documents with the hyphenated word pair.Example

full-text

Finds documents containing “full-text.”

Notes view – Yes
Notes domain – Yes
Web view/domain – Yes

Intermission

What? An intermission? Yeah, well, I started this post DURING IBM Connect in January. When I got back and tried to implement using query strings in my sample database, I crashed the development server 4 times in a row. The server was still on 8.5.3 and my need for query strings was not high. Fortunately, I’m on vacation at the beach as I write this. Yes, during a week of gorgeous weather in the Outer Banks of North Carolina, I am reading Mastering XPages and adding an entry to my blog. Some people read trashy novels at the beach, but I follow the example of Montgomery Scott and read technical manuals. Ok, so back to the topic….

Coding the call

Passing the query string from our report configuration documents to our function really isn’t that hard. I worried a lot about those crashes, so I started coding defensively, though I didn’t go so far as to add a try-catch block into the code. That will likely be inserted in the next version (after all, I expect to return to this as I get more savvy with POI’s Excel tools).

All we have to change in our code is to pull both the query string and sort column name from the report configuration document and append those string values to our function call.

	var queryString = doc.getItemValue("QueryString");
    var sortColumn = doc.getItemValue("SortColumnName");
	postValidationError(control,"queryString length: " + queryString.length );
	if ( queryString.length == 0 ) {
		createWorkbookStreamWithLabels(wbName,sheetName,colFields,dbName[0],viewName[0],labels,totalLabels,"","");
		return;
	}
	if ( queryString == null ) {
		postValidationError(control,"queryString null");
		createWorkbookStreamWithLabels(wbName,sheetName,colFields,dbName[0],viewName[0],labels,totalLabels,"","");
	} else {
		if ( queryString [0] == "" ) {
			createWorkbookStreamWithLabels(wbName,sheetName,colFields,dbName[0],viewName[0],labels,totalLabels,"","");
			postValidationError(control,"queryString empty");
		} else {
			createWorkbookStreamWithLabels(wbName,sheetName,colFields,dbName[0],viewName[0],labels,totalLabels,queryString[0],sortColumn[0]);
		};
	}

Applying the QueryString

Now, all we have to do is insert the query into our Excel sheet creation function. It’s actually very simple, as FTSearch and FTSearchSorted both modify the view object. You can simply drop the code in anywhere after you get a handle to the view and before you start processing documents.

Interestingly, after you apply either FTSearch or FTSearchSorted, the view remains sorted in original view order ONLY if the database is not full-text indexed, otherwise, it is sorted by relevance. In FTSearchSorted, you can override either behavior by selecting one column to sort instead (ascending or descending, of course). FTSearchSorted also allows you to use either a single query or a vector of queries.

Both methods return an integer count of the number of documents found by the search, so, in my code below, I simply return if there are no documents found. Yes, it ought to be fancied up, but I want to get this code out, so functionality is all I’m after today (There is Provencal rose’ chilling in the refrigerator, after all.) Here’s our code:

    //apply the queryString
    postValidationError(control,"Entries: " + myview.getEntryCount());
    if ( queryString != "" ) {
         postValidationError(control,"Sort Column: " + sortColumn);
        // max number of documents return is set as myview.getEntryCount() so that all view entries could be returned
        // default sort order is ascending
        var docCount = myview.FTSearchSorted(queryString,myview.getEntryCount(),sortColumn);
        postValidationError(control,"Query: " + queryString);
        postValidationError(control,"Query count: " + docCount);
        if ( docCount == 0) return;
    }
    postValidationError(control,"Queried view entry count: " + myview.getEntryCount());

Syntax for FTSearchSorted

FTSearchSorted(query:string) : int

FTSearchSorted(query:string, maxdocs:int) : int

FTSearchSorted(query:string, maxdocs:int, column:string) : int

FTSearchSorted(query:string, maxdocs:int, column:string, ascending:boolean, exact:boolean, variants:boolean, fuzzy:boolean) : int

FTSearchSorted(query:string, maxdocs:int, column:int) : int

FTSearchSorted(query:string, maxdocs:int, column:int, ascending:boolean, exact:boolean, variants:boolean, fuzzy:boolean) : int

FTSearchSorted(query:java.util.Vector) : int

FTSearchSorted(query:java.util.Vector, maxdocs:int) : int

FTSearchSorted(query:java.util.Vector, maxdocs:int, column:string) : int

FTSearchSorted(query:java.util.Vector, maxdocs:int, column:string, ascending:boolean, exact:boolean, variants:boolean, fuzzy:boolean) : int

FTSearchSorted(query:java.util.Vector, maxdocs:int, column:int) : int

FTSearchSorted(query:java.util.Vector, maxdocs:int, column:int, ascending:boolean, exact:boolean, variants:boolean, fuzzy:boolean) : int

Parameter Description
query The full-text query or the intersection of multiple queries. See below for the query syntax.
maxdocs The maximum number of documents you want returned from the search. If you want to receive all documents that match the query, specify 0. Defaults to 0.
column The name or 0-based index of a sorted column. A specification of NotesView.VIEW_FTSS_RELEVANCE_ORDER (512) returns results in relevance order while honoring the use of the extended flags for exact case, variants, and fuzzy search.
ascending Sorts column data in ascending order if true, descending order if false. Defaults to true. Ignored if NotesView.VIEW_FTSS_RELEVANCE_ORDER is in effect.

The availability of a column to be sorted in ascending or descending order is determined by “Click on column header to sort” on the Sorting tab of the column properties. The relevant options are Ascending, Descending, and Both. Trying to sort a column in an unsupported direction throws an exception.

exact Applies exact case to the search if true. Defaults to false.
variants Returns word variants in the search results if true. Defaults to false.
fuzzy Returns misspelled words in the search results if true. Defaults to false.

Epilogue

So, using the code above, you should be able to create report configurations that produce sorted Excel sheets to any device. My favorite is to create on on my Motorola Xoom tablet and show people data from our databases right there. I’ll keep working on this because I’m sure I will need to sort in multiple columns. I know that if I put each of the entries into an array list, I could use multi-value sorting from Java, so I might pursue that.

I’ve updated the file on dropbox.

Categories: Server-Side Javascript, Utilities, Xpages | Tags: , , , , , | 3 Comments

Simple view without links in #xpages

One of my co-workers, Neil Enet, asked me the other day if it was possible to set up a view but prohibit the users from opening the documents. I tossed out the idea of using an HTML table with all the HTML for the rows and cells being computed in one column of a view.

"<tr><td>" + approverName + "</td><td>" + approvalType +"</td><td>" + description"</td></tr>"

Unfortunately, that’s pretty clunky and not very satisfying. So, as we talked, I said, “Hey, how about you create an XPage with a view and just don’t make any of the columns clickable?” So, he did.

I asked Neil to comment on it, and he had some great thoughts:

My first XPage. I’ve never competed on a race before, but I imagine the feeling of winning one as being pretty similar to seeing this XPage for the first time. And OK, let’s be honest, it’s a pretty simple XPage. “Simple” might be too much of a word, actually. It’s just a view. ONE view.

The process was extremely easy. I just dragged the View Control, linked it to the view in Notes that I wanted, and voilà. I changed the font size and color of each column, and that felt like an even more awesome achievement.

The funny thing is I’m sure that if I never had the need to create a view like this, where users weren’t able to open documents, this wouldn’t have been so fulfilling. I can see myself saying: “Great, I just created a view, and you can’t open any docs. What’s the big deal about THAT?” But it turns out that that’s exactly what I needed. So simple! And to think that Old Notes didn’t allow me to do this, and that I had to go down the “terrifying” XPages way. Ha!

I can’t think of a better way to start playing with XPages. I now know I can do one, and I know I’m being very naive if I say “XPages is a piece of cake”, but there it is on my system, and I’m sure it will not be the only one.

I’m looking forward to creating more complex XPages, and it’s very very exciting. I might just take a picture of my XPage and put it next to my wife’s here on my desk. And when people walk by and ask me what that is, I’ll answer: “That’s the most simple XPage in the world. But you know what? It’s MY simple XPage.”

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">

<xp:viewPanel rows="30" id="viewPanel1">
	<xp:this.facets>
		<xp:pager partialRefresh="true" layout="Previous Group Next" xp:key="headerPager" id="pager1">
		</xp:pager>
	</xp:this.facets>
	<xp:this data>
		<xp:dominoView var="view1" viewName="COPApprovals"></xp:dominoView>
	</xp:this.data>
	<xp:viewColumn columnName="$11" id="viewColumn1" style="font-weight:bold;color:rgb(0,0,160)">
	</xp:viewColumn>
	<xp:viewColumn columnName="$10" id="viewColumn2" style="font-weight:bold;color:rgb(0,64,0)">
	</xp:viewColumn>
	<xp:viewcolumn columnName="$12" id="viewColumn3">
	</xp:viewColumn>
</xp:viewPanel>

</xp:view>

Then, to get users to access it from their Old Notes, using an Outline Entry to open the URL….

targetXpage := "internalApprovals.xsp";

server := @Subset ( @DbName; 1 );
path := @Subset ( @DbName; -1 );

fserver := @Name([CN]; server);
fpath := @ReplaceSubstring(path; "\\"; "/");

url := "notes://" + fserver + "/" + fpath + "/" + targetXpage;

url

And now, Neil has developed his first XPage, users will be able to see status on their documents and everyone will be happy. (Well, I’ll be happier once he goes back in and names the columns in the old view, gives better IDs to the XPage viewColumns, puts it all onto an application layout control and makes everything pretty, but, it works!)

So, if you’re still in fear of XPages, you needn’t be. Go forth and be LOST IN XPAGES with the rest of us!

 

Categories: Old Notes, Xpages | Tags: , , | 2 Comments

Dirty pages and keeping users on them in #XPages

As I’ve mentioned before, sometimes XPages does not react the way your Notes users would expect it to react. In particular, I’ve had issues with ensuring that XPages warns the user when they try navigating away from a page that they’ve edited without first saving it. Such pages are “dirty”, since something has changed on them. Back in November we examined this in my post on Modified flags in XPages.

Unfortunately, sometimes I want to inform the user that they’re leaving a dirty page and other times I don’t. Also, sometimes, I seem to be able to add things that don’t warn the user that they’re leaving a dirty page. I’m sure there is consistency, but I haven’t figured out the rules, so I have added some code that handles these situations.

Simple warning of a dirty page

This was described in that prior post. Set the enableModifiedFlag to true and provide a couple of properties to handle it. This should fire whenever you close the XPage or navigate away via a standard link.

<xp:view xmlns:xp="http://www.ibm.com/xsp/core" enableModifiedFlag="true">
	<xp:this.modifiedControl>
		<![CDATA[#{javascript:if ( true ) {return "saveButton1"}}]]>
	</xp:this.modifiedControl>
	<xp:this.modifiedMessage>
		<![CDATA[#{javascript:"Purchase order modified. Click OK to save, cancel to continue without saving"}]]>
	</xp:this.modifiedMessage>
...
</xp:view>

Unfortunately, I’ve found that sometimes, it doesn’t warn me.

Warning when clicking links

I’ve got some navigation on the left side of my XPages, set up in a lovely dojo accordian with links to different parts of the application. However, not every link is set up in the same way. Some are simple and use the modifiedControl to warn users, like this one:

<xp:link text="Attachments" escape="true" id="link3" value="/att_attachmentManagement_view.xsp">
</xp:link>

Some, however, run some scripts to remove some sessionscope variables when switching pages and I was having challenges getting the server-side Javascript to execute. So, I found a way to do both:

<xp:link text="Payment requests" escape="true" id="paymentLink" target="_self" value="#">
	<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
		<xp:this.action><![CDATA[#{javascript:clearDynamicViewSettings();
context.redirectToPage("/pro_paymentRequest_view.xsp");}]]></xp:this.action>
	</xp:eventHandler>
</xp:link>

The unfortunate thing is that when I’m using the redirect, it ignores the dirtiness of the page. Fortunately, Per Henrik Lausten found a way to deal with it on StackOverflow (thanks to PSolano), and posted it as an XSnippet on OpenNTF.

if (XSP._isDirty()){
  if (confirm ("Are you sure you want to navigate away from this page?" + "\n" + "\n" +
    "This document may contain unsaved changes." + "\n" + "\n" +
    "Press OK to continue, or Cancel to stay on the current page.")) {
    return true;
  } else {
    return false;
  }
} else {
  return true;
}

So, when I added that explicitly as client-side Javascript to each eventhandler, it worked beautifully. Now, being a fan of reusable code, I wanted to put it in a CSJS script library and invoke the function all over the place. My function was as shown above, with a little wrapper:

function isClean() {
	if (XSP._isDirty()){
	    ....
	}
}

Then, I just needed to invoke it. My first attempt looked great to me. Call isClean() and the client side would warn the user, then stop them as appropriate.

<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
	<xp:this.action><![CDATA[#{javascript:clearDynamicViewSettings();
context.redirectToPage("/pro_paymentRequest_view.xsp");}]]></xp:this.action>
	<xp:this.script><![CDATA[isClean();]]></xp:this.script>
</xp:eventHandler>

Ummmm, but that didn’t work. In order to prevent the server-side Javascript from executing, the client-side Javascript needs to RETURN false, not just compute it.

<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
 <xp:this.action><![CDATA[#{javascript:clearDynamicViewSettings();
 context.redirectToPage("/pro_paymentRequest_view.xsp");}]]></xp:this.action>
 <xp:this.script><![CDATA[return isClean();]]></xp:this.script>
</xp:eventHandler>

That’s added bonus knowledge – not only are we learning how to stick to dirty pages, we’ve also learned that if you have the CSJS return a value of false, it will not execute the SSJS. I’m sure you can grasp the opportunities for validation provided there.

What about when you don’t want to warn them?

In our application, the user can select the action to perform from a combobox and then click a button to execute it. (Thanks to Scott Good, Henry Newberry and the folks at Teamwork Solutions!) The challenge here is that when the user changes the value in the combobox, the page is dirty! I mean, no data may have changed other than that combobox, but the XPage still feels dirty. Since some of those actions will result in saving the document and all of them result in navigation away from this page in an expected and managed way, we don’t want it to feel dirty. To dodge the problem, I just add a little CSJS to convince that page that it’s not really dirty.

<xp:this.script><![CDATA[XSP._setDirty(false,"");]]></xp:this.script>

So, then the modifiedControl is not tipped off and we execute the intended commands. Now, I’m pretty sure we don’t run into this problem with standard save buttons, but we’re in an unusual case of taking two steps to execute one action.

Note

YMMV. These private calls to XSP methods may go away and using them requires care to ensure you’ve got the right parameters, or so the XPages Portable Command Guide advises us. Of course, everything we code may call functions that will go away and we always need to get the parameters right. So, I’m gonna use them, though sparingly.

Categories: Client-Side Javascript, Server-Side Javascript, Xpages | Tags: , , , , , , , , , , , , | Leave a comment

Sample database for #Excel exporting from #XPages

Folks had asked if I could provide a sample database beyond just the coding examples I’d provided (part 1 and part 2), so I got ready to upload one. Then, I thought, “I bet I can add full-text searching to that real easily.” Unfortunately, I hit snag after snag on adding the full-text searching, so I decided I’d post what I have working.

When I do finish up the full-text search capability, I will not only write about how I coded that, but update the sample database as well. Until then, enjoy the sample!

Categories: Utilities, Xpages | Tags: , | 7 Comments

Copying design elements via script in #XPages

One of my first posts was about copying a view from one database to many using XPages. Well, as I was surfing the help documents to learn more about FTSearch in order to extend the capabilities of my Excel exporting capabilty, I found createNoteCollection.

createNoteCollection can be used to create a collection of all notes in a Notes database. That is, not just Notes documents, but all Notes design elements. Not only that, but you can quickly choose what kind of notes you want in your note collection. While there are boolean parameters for each type of note you might want, I am most intrigued by the combination ones, which allow you to select by category.

selectAllAdminNotes (ACL and replication formulas)
selectAllCodeElements (agents, database script, outlines, script libaries and misc code elemnts)
selectAllDataNotes (documents AND profile documents)
selectAllDesignElements (code, format, index, help, icons and shared fields)
selectAllFormatElements (actions, forms, framesets, image resources, java resources, misc format elements, pages, style sheets and subforms)
selectAllIndexElements (folders, misc index elements, navigators and views)
selectAllNotes (everything)

So, once you create  your note collection, then you can walk the collection using getFirstNoteID and getNextNoteID, accessing each design element (or document). Then, using NotesDatabase.getDocumentByID to get a handle to it as a NotesDocument, so you can use NotesDocument.CopyToDatabase to copy the design element across to the new database.

var db:NotesDatabase=database;
var notecollection:NotesNoteCollection=db.createNoteCollection();
notecollection.selectAllDesignElements();
var noteID:String=notecollection.getFirstNoteID();
var note:NotesDocument;
var nextNote:NotesDocument;
while ( noteID != null ) {
	note=db.getDocumentByID(noteID);
	if ( note != null ) {
		note.copyToDatabase();
	}
	noteID=notecollection.getNextNoteID();
	nextNote=db.getDocumentByID(noteID);
	note.recycle();
	nextNote=note;
}

Now, it is a little blunt to grab all design elements and copy them from one database to another. One problem is that you are certain to have some duplication of design elements and I’m sure that will create problems. I know that I was able to have two identically named views in my original post, so I didn’t copy the view if it already existed in the destination database. So, you might want to create collections in both databases and compare the design notes t0o make sure not to create duplicates (either by deleting the one in the destination database first or simply not copying the new one in).

Categories: Old Notes, Server-Side Javascript, Utilities, Xpages | Tags: , , | Leave a comment

Finding user roles in #XPages

I’ve written a piece before on roles in XPages, but since that dealt with using the ACL to limit access to a page and not about the programmatic use of roles, I wanted to return to the issue.

Back in old Notes, if we wanted to hide something based if the user did not have a certain role in the ACL, we could use a pretty simple formula:

!@IsMember(“[roleNameHere]”; @UserRoles)

Remarkably, it’s not that much harder in XPages, but there are some important wrinkles to be concerned about. As noted previously and by Russ Maher on his blog, you must remember to use your brackets [] and also keep in mind the result you want (true or false). Remember that the XPages formulas are ‘rendered’ formulas, meaning you want to ‘true’ to display the result and ‘false’ to hide it, so you’d use:

@IsMember(“[roleNameHere]”, context.getUser().getRoles());

Here’s the more complete source code for the rendered formula:

<xp:this.rendered><![CDATA[${javascript:@IsMember("[Testing]", context.getUser().getRoles());}]]></xp:this.rendered>

Now, I’m not sure what impact of referencing the user roles that way has on performance, but since I now I’m using them in many rendered formulas all over my application, I decided to compute it once and then reuse it many times. I put a few extra lines into a control that’s on my main application layout control to drop it into a sessionscope variable. I suppose I might shave a millisecond off if I only computed that once per session, but I didn’t go that far.

<xp:this.beforePageLoad>
<![CDATA[${javascript:var roles = context.getUser().getRoles();
sessionScope.userRoles = roles;}]]>
</xp:this.beforePageLoad>

Then, in order to check to see if my user has one of three roles when rendering an item, I could use this code:

<xp:this.rendered><![CDATA[${javascript:var manager = @IsMember("[InventoryMgr]", sessionScope.userRoles);
var viewer = @IsMember("[InventoryViewer]", sessionScope.userRoles);
var grantsManager = @IsMember("[InvMgrGrants]", sessionScope.userRoles);
if ( manager || viewer || grantsManager ) { return true };
return false; }]]>
</xp:this.rendered>

Now, I also found that sometimes I need to determine the user’s role in my Java code. That’s also not that hard, except that vectors are not quite arrays. If there is a single value, it’s not the same as a multiple value vector. I’m not sure if this is a Notes implementation issue or if it’s the way Java always handles vectors. That is, if it’s a single value, it puts our brackets [] around the value, but it does NOT for multiple values. So, when I was using the code written for us, it wasn’t always picking up the roles correctly. Once I simply told it to check both ways, our code worked more cleanly. (The reference to ExtLibUtil comes from the original code, so I didn’t modify it.)

public Vector getCurUserRoles() {
	try {
		curUserRoles = ExtLibUtil.getCurrentDatabase().queryAccessRoles(ExtLibUtil.getCurrentSession().getEffectiveUserName());
	} catch (NotesException e) {
		this.debug("getCurUserRoles ERROR: " + e.getMessage(), "error");
		curUserRoles = new Vector();
	}
	return curUserRoles;
}

public boolean hasRole(String role, String uname) {
	try {
		Vector roles = this.getCurUserRoles();
		if (roles.contains(role))
			return true;
		if (roles.contains("["+role+"]"))
			return true;
		return false;
	} catch (Exception e) {
		this.debug("hasRole ERROR: " + e.getMessage(), "error");
		return false;
	}
 }

Note that the debugging uses Mark Leusink‘s DebugToolbar, which I highly recommend to everyone.

Categories: Java, Old Notes, Security, Xpages | Tags: , , , , , , | 2 Comments

Create a free website or blog at WordPress.com.

%d bloggers like this: