 Paul Withers
 Tim Malone
| Paul Withers 31 August 2010 09:09:26 AMIt's been a busy few weeks for me, which is why I haven't posted as much as I would have hoped. Although the immediate deadlines have passed, that leaves me no less busy, because next week I am speaking at NLLUG in Amsterdam on 9th and 10th September. The session is XPages from a Different "View"-point an update to the session I delivered at BLUG earlier this year. This weekend I was going through the slides and the sample database, and I was able to take advantage of a number of things I've learned in the last six months. The session is aimed at beginner to intermediate, but hopefully there will be plenty of valuable information for developers of any level. Then in November I will be speaking at ILUG in Belfast on 10th - 12th November. At that conference I will be presenting a new session called XPages: Enter the Dojo. As the name implies, this will be looking at integration of Dojo with XPages, made easier in 8.5.2 by the Dojo tab of the Properties for each element. But, as the session will show, that's not the only way to integrate Dojo with XPages. This session is aimed at intermediate to advanced. If you're attending either of the Lotus User Groups, please do come and see me. Paul Withers 27 August 2010 10:56:50 PMSome time ago I produced a video, on Intec's channel on youtube, showing how to use an XPage to create a live-text enabled widget. The beauty of this technique is it works in any 8.x Notes Client, it just needs a Domino 8.5.x server. I'm currently using the same technique to create a reporting sidebar panel for one of our customers. At the time I intended to add a second video showing how to create a live text recognizer so that you could right-click on a date to launch a floating window that displays documents based on that date. I was asked a number of times to provide a sample database, and intended to package the two. Unfortunately things have been rather hectic and, for all my good intentions, I never got round to doing that part. And I can't see it happening in the short term either. So I've attached a sample database with the relevant XPage - you'll notice it looks a bit smarter than in the video. To give the background, there are two XPages - personWidget.xsp and personWidgetBrowserTest.xsp. The latter is designed to allow you to test everything's set up correctly. You can type in a name, and an onblur event pulls the relevant person's information from the names.nsf on the same server as the sample database. The former is the one used by the widget - the name is passed by the live text. I would strongly recommend following the instructions in the video for creating the widget yourself. This is the most foolproof way and I strongly believe it is of benefit for a developer to understand how to do it. You'll need to if you want to create your own widgets, which is the main reason I created the video. And, believe me, it's not rocket science. But if you really don't want to do that, open the sampleExtension Page in a browser, save the content as extension.xml and drop it into your My Widgets panel. This should generate the required widget, authenticating against an account called intranet, but it is very much a hack. You can compare your final extension.xml to the extension.xml file resource in the sample database. Needless to say the server name is not accurate, and the sample database is not on any of our public servers. One other points of note: in the video I use a floating window because the live text spawns multiple sidebar panels, if that is used as the source. 8.5.2 introduces the singletonSidebar attribute, which allows you to reuse an existing sidebar panel. However, as far as I am aware, this will only work if the Notes Clients you deploy to are 8.5.2. Lastly, I want to reiterate that the sample database is to show how to do it. It's not designed as an app to deploy to end users. I am sure I don't need to outline the possibilities for integrating live text with existing applications, to enable users to perform simple functions directly from their email. The applications in question don't necessarily need to be XPages applications. Indeed your code doesn't even need to be in those databases. And the same technique can be used to produce sidebar panels for allowing users to perform simple functions or, as I'm doing at this moment, offer reporting. It opens the possibilities for getting into XPages without the daunting challenge of redesigning whole applications, leveraging your company's investment in Domino and showing your users what's possible if they dare to dream. Paul Withers 10 August 2010 10:07:22 PMWith today's announcement of a release date for Domino 8.5.2, it seems the right time to review some of the features I've come to like in the closed beta. Some of them are just usability enhancements, others are functionality enhancements, and many are XPages enhancements. Before continuing, I must include the caveat that this article is based on the 8.5.2 Code Drop 5 beta, and that code is not guaranteed to be included in the Gold release due on August 24th. Help The quality of the Help files in 8.5.2, particularly for XPages, has been widely criticised. The Help in 8.5.2 has been improved significantly. But also the Server Side Javascript editor has been enhanced, with a new library, Control Declaration Snippets, available. Other libraries have been enhanced so that, for example, the javascript Error object is listed and its properties and methods visible for the first time. One of the points this raised to me recently is that e.getMessage() to capture an error messahe in a try...catch block, which works in 8.5.1, is not the properly supported way to output the error message. Instead it's e.message, which works in 8.5.1 as well as 8.5.2. If you have used this in applications, it's worth changing as soon as possible. Since the discussions in blogs some weeks ago about the quality of Help materials, those who watch the Lotus Notes & Domino Application Development Wiki will have seen a plethora of 8.5.2 focussed articles, particularly focussed on how to use new functionality. While talking about the wikis, it's nice to see something I raised on an LTIE call some time ago included in the Designer Client, namely that the links under Help - Lotus Internet Resources allow developers direct access to the wikis. XPages Editor Many of the XPages wizards have been enhanced to make attributes more accessible, most notably in the View Panel where the ability to filter on category or column value, with or without exact match, is readily available, as are search and sort column attributes. Other wizards (e.g. those for Panel and Edit Box controls) have a Dojo tab where the Dojo type and attributes can be defined. All these options have been in the past and are still available on the All Properties tab. But by having a specific tab it makes this functionality more visible. And on the All Properties tab, Dojo-related attributes of the relevant controls are categorised under their own category, making them more visible there too. In the beta you still need to know what Dojo types are applicable to what controls and what Dojo attributes can be applied, for which I would recommend the Dojo toolkit reference guide. Bear in mind that you will need to take into account the relevant Dojo version - in the beta this is 1.4.3 but 1.5 is now released. I will be waiting to see which version will be shipped with the Gold release. Wizard enhancements also extend to the XPage and Custom Control wizards, where the Resources tab allows all resource types to be inserted. These include metadata and linked resources, both new in 8.5.2. Resources can now have a media type defined, allowing specific stylesheets or other resources to be available for e.g. print, projection, handheld or braille. After working with XPages for over a year now, most of my work is in the Source pane. Some minor frustrations have been resolved there too. Controls can now be dragged and dropped into the Source pane although XML for controls can also be typed. In 8.5.1 if you type the name for a Custom Control in the Source pane, you get a message that the control is not bound. That too has been resolved. While talking of minor annoyances, you no longer need to close and re-open an XPage or Custom Control for the Data Palette to be updated. The rich text editor used by default is now the CKEditor, although the Dojo rich text editor is still available. CKEditor looks good and offers great usability enhancements. And, in the same way as the Dojo editor can be extended (as I blogged a few months ago), so too the CKEditor can also be extended. There are also a number of enhancements in XPages code, of which I think two are particularly worthy of mention. Anyone who has tried to use a partial refresh on an XPage which has required fields will know there are challenges: if you do not tick "Do not validate or update data", the validation is triggered; if you do tick it, you cannot set values through SSJS and use them. (There are ways through it, e.g. validating via Input Validations on your Form and setting the computeWithForm property of your Data to onsave.) But fortunately in 8.5.2 there is a new option for partial refreshes - "Process data without validation". I can see this being of significant benefit in the future. The second are new Global Objects - sessionAsSigner and sessionAsSignerWithFullAccess. This ability to run different pieces of code on a single XPage under different authorities I can envisage being invaluable. I am unaware of the technical challenges of this, but it would be nice to have had this functionality extended to LotusScript as well. Others There are some additions to the Properties for Domino Designer. Default language types can be set for Script Libraries, Agents, Web Service Providers and Web Service Consumers. This will be useful, whether set once or amended based on current projects being used. There is also the option to enable Eclipse plug-in install. There have also been significant improvements with Working Sets. For those who use them this will be very welcome. And when opening applications in Designer users will see a very different and, in my opinion, much improved Open Application dialog. As has been mentioned elsewhere, applications can nw be signed in the Designer Client, a very welcome addition for developers who otherwise only use the Administrator client to sign a database. Design element properties have also subtly been enhanced, with Forms etc. now showing the Modified In version. XPages elements show a Compiled for version. This will be particularly useful when XPages applications are being delivered to different 8.5.x (or RNext) servers. There are additional benefits I haven't mentioned. Some like the Single Copy XPage Design I haven't used yet. Others like the XPages Extensibility API I don't feel confident enough to play with yet. Paul Withers 5 August 2010 10:09:34 PMThis follows on from two previous articles where I outlined what became evident from the oneui themes, ways to reference server-based resources from XPages. Those articles (Part One and Part Two) concentrated on images, the most useful resource. Like many developers, at Intec we have a suite of databases with resources (some images, css files, script libraries etc) residing in a single database. When referencing resources, if you prefix the database path with "/" the output HTML is prefixed with the current database path as well. This resulted in me using SSJS to get the full host name and protocol ("http" or "https"), not a pretty or good-practice way of doing it. Today, when challenged by one of my colleagues, I finally put two and two together and realised that by using "/.ibmxspres/domino" I get to the data folder, from which I can navigate to sub-folders. (At times I can be rather slow!) So instead of referencing the protocol and host name, I can use "/.ibmxspres/domino/" + the database path to reference another database on the same server. Paul Withers 28 July 2010 01:55:26 PMWhen I first started on XPages last year, one of the big benefits was that virtually anything can be computed. When you do so, you get the option to use three languages: Expression Language (EL), Server Side Javascript (SSJS) or Custom. I immediately started using Server Side Javascript, but the others were a bit of a mystery. If you have experience of JSF or JSP, you'll know about Expression Language. But as a developer whose main experience was Notes Client development, and some classic Domino web development, it meant nothing to me. If I'm not the only one, hopefully this blog post will demystify it all and allow you to reduce the amount of typing by combining languages (that's the Rosetta Stone reference, that you're using all languages side by side). The process for me when I tried to understand the languages is the same as I've used to try to understand other areas of XPages: use the wizards and look at the Source pane. The first thing to say is that there are actually four languages instead of the three mentioned above. There is also the default language for content. This is usually a literal string, but for some events like onComplete the default language is client-side javascript. Loaded vs Rendered If you look at the Source pane, you'll notice is that if you use EL or SSJS the content is wrapped by default in "#{...}". If you've extended this further, you'll also have come across "${...}". What I found out recently when I started reading The Complete Reference: JavaServer Faces 2.0 is this is based on Expression Language in JSF, where the same two concepts are used. If the hash is used, your code is recomputed every time that element is included in a partial refresh (i.e. each time it is rendered). If you use a dollar, your code is only computed when the page is initially loaded. But this has been extended beyond just EL, to SSJS too. After the hash or dollar, the curly braces denote the start and end of your language. This will be important when we come to combining languages later. As I said, by default everything is wrapped in "#{...}", but once you get past early development, it's well worth using "${...}" where appropriate to maximise performance. However, bear in mind that if you're referencing output from e.g. a repeat control, you may not be able to use "${...}", because the relevant underlying objects have not been created early enough in the lifecycle. (The lifecycle and when objects are created is an area I'm still getting to grips with.) Expression Language (EL) Now for the languages. EL uses dot notation to bind to a NotesXSPDocument object (i.e. a DominoDocument datasource), a NotesXSPViewEntry object (i.e. a row of a DominoView object) or a scoped variable. The former is straightforward, and the dot notation binds to a field. The binding is read-write, so providing you have author access to the underlying NotesDocument you can modify the value. (The way I tend to think of it is that the DominoDocument datasource, the NotesXSPDocument, is the equivalent of the NotesUIDocument in classic Notes Client development, so if your datasource is designated document1 - var="document1" in the source - document1.getDocument() gets the back-end NotesDocument object.) The latter is slightly more convoluted. If you have a DominoView datasource and use it as the source for a View Panel, Data Table or Repeat Control, the NotesXSPViewEntry object gives you access to each row and the dot notation binds to a column in the view. The DominoView will have a variable name which is used to bind the view to a View Panel, Data Table or Repeat Control (e.g. value="view1"). The View Panel, Data Table or Repeat Control can have a variable name (you need to define it, e.g. var="viewEnt") to access a NotesXSPViewEntry. The binding references the name of a column, so "#{viewEnt.FullName}" binds to a column called FullName. Bear in mind that the binding is read only, so if you have an editable field (xp:inputText) bound to a column name on a NotesXSPViewEntry, what you will see is a Computed Field (xp:text). If you want to edit the value, you need to set the value to be the relevant field from the underlying NotesDocument object, and write your own code to save the value back. As you'll see from the format of "#{viewEnt.FullName}", the content within the curly braces is just the EL. If you have a short expression, what you'll see on the All Properties tab is # viewEnt.FullName. Cross-reference with the source pane and you'll see value="#{viewEnt.FullName}". So by selecting EL, the editor automatically inserts the hash and automatically populates the source accordingly. Server-Side Javascript (SSJS) SSJS, as anyone who has looked at the source pane will have seen, follows a similar format, but the content within the curly braces is prefixed with "javascript:", so e.g. "#{javascript:@Subset(@DbName(),1)}". (And this is a perfect example of where you would in preference use dollar, because the server name is not going to change when partially refreshing the page, so you would use "${javascript:@Subset(@DbName(),1)}"). If you think about it, this is understandable because the rest of the syntax to compute values is based on Expression Language in JSF. But something is needed to tell the XSP engine that this is not Expression Language, that a different parser is required. And that's why it is prefixed by javascript:, to tell it to use SSJS (no additional prefix is required, because CSJS is not an option, so there can be no ambiguity by using the term javascript:. Custom But when you look at the drop-down for languages, there is a third, Custom. For this you get no help, no explanation of what it means. But in actual fact it's very simple. It means that you are combining languages, and this is where the power of XPages comes in and where you can really speed up your development. By using the syntax from the source pane I've already described, you can combine languages. So instead of using a label and computed field, or two labels, or two computed fields, you can combine multiple expressions of all the languages I've outlined. So let's just paraphrase what those languages are. "Name" is a literal string. "#{document1.Name}" is EL, returning the Name field from a document1 datasource (this will always be a text value - you need to add a converter to manipulate the value). "#{javascript:doc.getItemValueString("Name")}" gets the value from a text field called Name on a NotesDocument or NotesViewEntry defined as doc. The quotes are always used around the various expressions. This means by using you can have a single Computed Field whose value is "Name is " + the Name field of the document1 datasource. You could equally use to have a single Computed Field whose value is e.g. "Username: Paul Withers" (again, this would be a good candidate for using dollar instead of hash). And you could use to have a single Computed Field that combines a NotesXSPViewEntry's Site column with the value of the Department field in the underlying NotesDocument, all separated by a space. Just remember that anything not in curly braces is a literal string, even a space is a literal space, so if you wanted site and department separated by a colon, with no spaces, you would need to enter . Once you become confident combining the three languages into the fourth Custom language, you can minimise the number of controls on your XPage and minimise the amount of typing in the source pane. Paul Withers 19 July 2010 02:44:03 PMThis morning I picked up a support query from a customer who was confused by the behaviour of an export. My customer was exporting a view to a csv file for import into a third-party application. Although I've written agents to import to and from text files with a specified delimiter, this was just using the normal Notes Client export functionality from File - Export. However, the output from the view in question was rather strange. One column showed a multi-value field, but with no specified separator, so the view column was: Value1,Value2,Value3 But only the first two values were being pushed out to the csv file. There was nothing unusual with the view except that the column was not wide enough to show all the entries, and I could only see part of the second value. Instinctively I expanded the column before exporting, so I could check what values I should be seeing. When I exported, I got all three values, not just the two the customer was getting. My customer was on an 8.5 client, so I tried that instead of the usual 7.0.2 client, but I still got the same output. However, when I then put the column back to its normal width, so I could only see two entries, like this: Value1,Val I only got two values in the csv export - "Value1,Value2". Strange behaviour, but I guess it's to do with the front-end export and overflows, that it is just exporting any visible or partly visible values. But it's worth being aware of if users will be exporting a view to csv. Paul Withers 9 July 2010 05:49:01 PMJust to remind anyone who didn't read my post last week, the gist was that I noticed my autosave database was very large, even though it had no documents in it and rarely had documents in it. The apparent cause was that default Space Savers setting on the Replication Settings was set, so documents were removed after 90 days, and deletion stubs after 30 days. So I made the seemingly obvious step of reducing the duration, so documents were removed after 3 days and deletion stubs would be deleted each day. This seemed a great idea. But all good plans and that... Since then, each day, 24 hours after I last got the prompt, if I create an email I am prompted: "The Replication Cutoff Date indicates that documents before 06/07/2010 16:29:36 should be purged from the database as_PWithers.nsf. Would you like it to be done now?" Considering that I've told it to delete the documents, I would expect it to do so, not prompt me. That's the behaviour I got when autosave was on and the default 90 days was used (because I've had autosave running since I installed R7 several years ago, and I've never had the prompt). But I can't find any setting to tell it to do so, or to disable the prompt. Perhaps there's an ini setting I'm not aware of. Or perhaps it's somewhere in the mail template (because a new mail triggers the alert). Regardless of all this, the most frustrating part is that I know that the autosave database doesn't contain any documents that old. Personally I can understand the message, and I know there's nothing to delete. But if this were rolled out to users, which would seem sensible, I can imagine helpdesks would receive a lot of calls. So unless anyone knows a solution, I'd have to say it's probably not a good idea to change the default setting for the autosave database. But it's frustrating that that give me a file 80Mb large. Paul Withers 28 June 2010 12:48:04 PMOur Domino Administrator noticed today that the as_XXXXX.nsf database was extremely large. This is the database used to store documents and emails if autosave is turned on. Autosave was a new option with R7, if my memory is correct, and although I've never used it for a Form in a database (most forms tend to be quite small), I've found it invaluable on a number of occasions for emails and Symphony documents. Being curious I also had a look at my own as_pwithers.nsf database. It was nearly 400Mb. When I opened the database there were no documents in any of the views, which is what I had expected. That's because I had not written any long emails today, and I didn't expect autosaved documents from a few days ago. But when I inspected the database I found a large number of deletion stubs. You can probably guess the reason, but if not the Help files explain: the purge interval for deletion stubs is 1/3 the number of days specified in the Remove documents not modified in the last x days setting on the Space Savers tab of the Replication Settings. Sure enough, that was set to the default of 90 days, so deletion stubs were only being removed after 30 days. Once I reduced the setting to 3 days, so deletion stubs are removed after a day and compacted the database, it reduced to 512Kb. This is unlikely to be a critical issue, but it's probably worthwhile reducing the setting for the autosave database whenever you're running maintenance or setting up a user. And if the users are on R8, you can also enable the Compress document data and Compress database design (the latter is less effective) properties on the Advanced tab of the Database Properties. After all, if a crash happens with unsaved documents, a user will usually recover the document as soon as they next open the Notes Client, not a number of days after the deletion stub is created. Paul Withers 23 June 2010 09:50:54 AMOver the last week I've been rather busy including some XPages functionality in an existing Domino web application, and as an example I wanted to explain why I chose XPages, some steps I took and the main challenge I encountered. XPages suited for this because: - We wanted the available documents to change depending on selections, so a view panel looking to a view filtered on key worked well.
- We could easily allow users to process multiple documents depending on selections using viewPanel.getSelectedIds()
- We could easily pull in information for multiple documents from multiple databases with good performance and show it with Dojo tooltips.
- We could allow users to edit certain information at the time they're selecting the documents.
- We could seamlessly call a server agent with agent.runOnServer, use masks in the onStart and onComplete events of the partial refresh and redirect on success, in fewer lines than I have done in the past by coding an AJAX post.
- We could use SSJS to easily pull only the relevant information I needed from the web page into a temporary document and get the values from that document in my agent. I have done an AJAX post in the past, pulling values from an HTML form. Considering the size of this page, in my opinion more coding would have been required in the whole process.
- We were able to create a quite sophisticated report using XPages, using my temporary document and child documents created by the agent. The report shows all children, regardless of the amount of docuemnts run on, allowing details to be expanded and collapsed (individually or en masse) using client-side javascript in the same way as normal web development. The XPage allowed functions to be performed on each child document with partial refresh with minimal coding. By using SSJS as well I could refresh the repeat control of child data while retaining the view of which child details were expanded and which were collapsed.
This is not the first time I've included XPages design elements into an existing Domino web application - I did the same in my first use of XPages. I'm sure it won't be my last. The first steps to take the current subforms that comprised the skeleton of the site and recreate them in an XPages custom control. One of the benefits here was that I could consolidate several subforms into a single custom control with an Editable Area in the middle of the content. It also validates my HTML, unlike pass-thru HTML on a subform. And it can be auto-formatted using Ctrl + Shift + F. As part of that I needed to include various resources, as well as a SSJS application initialisation script to pull paths to resource databases and some keywords into applicationScope variables. This is a basic bit of script in the beforePageLoad that begins "if (applicationScope.initApp==null)" and ends "applicationScope.initApp=true". Most time was spent implementing the existing stylesheets. This is not uncommon and I would always factor in time to fully reproduce the look and feel. The main area of frustration was styles allocated to elements by id, e.g. #contentArea {position relative; margin-top 15px; margin-left: 15px;margin-bottom: 15px; margin-right 15px} Anyone who has looked at the source HTML of an XPage knows element IDs get manipulated, and without that we couldn't have repeat controls. But even if I added an HTML div with an id "contentArea" I still got unpredictable results. The solution was to create a custom stylesheet for use in XPages that allowed me to allocate these styles to classes instead. I'm not completely recreating the stylesheet, but I am including an additional stylesheet in XPages design elements. This does require additional maintenance if there are changes to the styles. Ideally if I was starting from scratch, I'd just use classes. All of this is a fair amount of work, but if you're planning on using XPages design elements in more of the application, as we are, it's effort that will pay off in the long run. Once done I was ready to create my custom controls for the process. For its performance, flexibility and development time for the functionality compared to classic web, it was a worthwhile activity. Paul Withers 15 June 2010 10:54:26 PMThere has been huge discussion over the last week on the future of Domino and how to maximise the power of the platform in the eyes of senior IT executives. That XPages is and should be part of that future, I am convinced. But recent discussions I have had, comments I've seen on the blogs and recent blog posts about the role of XPages in the future also concern me. I'm not concerned that XPages is not known. I'm concerned that developers and especially senior IT executives don't get the real power of XPages. More importantly, I'm concerned that it is seen as a replacement for classic Notes or even classic web development, that those skills are being denigrated, that a classic Notes or classic web Domino application is out-of-date, a legacy app on a legacy platform. I think there is a risk that developers see XPages as something that should be used to redevelop their existing apps or to build new apps. If CIOs think you need to redevelop an app for it to be relevant for Notes 8.x, the argument will be to redevelop outside of Domino. For the last year I've been heavily involved in XPages development, I believe it is the future, not for what it is, but for the variety of implementations. Although it has great power for new applications (the ability to develop with a similar interface for client and web), I have recently started to look at XPages as more than a tool to develop an application, as a tool to develop an interface: widgets, live-text enablement, within composite apps, in the future for mobile enablement through tools like TeamStudio Unplugged for native delivery or just as web interfaces, and I believe they can also be used as components in mashups in Websphere Portal. I'm not seeing XPages as a tool to redevelop existing apps - none of us have the time or money to do that for our whole suite. Instead, I'm starting to look at XPages as a tool to add additional business benefit to existing apps, allowing users to perform individual functions that comprise parts of an application quickly and easily from the appropriate interface - a mobile device, a sidebar plugin, live-text, a component in an intranet. It's not about building the whole application in XPages. It's about offering users information from one or multiple related databases in a single interface to allow them to complete a task efficiently and effectively. That, I believe, is the true power of Domino and XPages. And I think there is a requirement for education on the this power - to developers, to CIOs, to end users. The problem is this power can't be shown easily in off-the-shelf demos of Notes 8.5. You can show how good an XPages application looks. That's great. But it doesn't show ROI or business impact. What is required is for a collaborative effort by IBMers and developers/business partners (like myself) to create a powerful demo that shows CIOs not something that just looks good, not just widgets that show social collaboration, but widgets and tools that allow business professionals to quickly perform appropriate tasks, to save themselves time, and so save their company money. That's the power of XPages and that is one of the things we're working on. The best use of XPages is not necessarily to redevelop your application that is just an icon or collection of icons on your workspace. Rather that it can be used to add to that existing application by providing a live-text action to allow users to approve a document without leaving their email, a sidebar widget that allows remote users to create a request or gives your management appropriate live reports, an interface on their iPhone or Blackberry for PART of an application, or a user-specific focussed set of functions within a portal. Is this an easy transition? No. It requires some time to understand what's possible. It requires imagination to think outside the box, from developers, from project managers, from users. And it requires careful project management: with so much possible, not all can be done for all projects, there needs to be prioritisation of what is most important for the project in hand. As I said, it's taken me quite some time to start stretching my wings in this direction. But if appropriate parties can highlight the power of XPages as an additional and not replacing element in the Domino toolkit, I do believe the power of Domino application development can effectively be demonstrated to stakeholders at all levels of the business. |
|
