OpenNTF Snippets – Investigating The Design

As you’ve hopefully seen, we’ve relaunched XSnippets as OpenNTF Snippets. There are quite a few changes, some decisions made that are less than traditional, but driven by some key factors. Indeed some may seem bad practice and are certainly not what may be made for other applications. But the driving force is a deep understanding of the application and its administrators.

Let’s show old and new side-by-side for a start.

Before we get into coding elements, the obvious. It’s XPages. There is a regular stream of what I frankly believe is rubbish and a lot of demands for the future that in my opinion are also unrealistic. XPages is not growing the platform and is not going to bring the kind of revenue that will justify the massive overhaul some are asking for. But XPages is rapid development. Apart from the new login area, the rest of the facelift of the site took less than a day and a half, even though it looks like a completely different site. And it looks modern and I will not be ashamed of the look if it doesn’t change for a few years. As long as XPages is supported, there’s no real reason to change this for a few years, even if nothing else is done with XPages for years to come.

Firstly, the theme has been changed from OneUI v2 to Bootstrap v3. To be honest, for some time that has been a preference for my web applications. But it also fits in with the more recent OpenCode4Connections site.

Beyond that, the navigation is a significant change from what was there before. Without meaning to be critical of the previous design choices, it’s a change from a typical early XPages application (my own included) to a web application. Instead of multiple views with different ways of sorting the content, we have a faceted search. The former is the way we do it in the Notes Client, because that’s the way we were taught to build a Notes Client application and because that’s the way Notes Client users are used to. And those were the initial target audience for XPages applications, so we built what was familiar. But there’s one critical difference: scrolling down a Notes view or using Quick Find is easy and quick in the Notes Client; it’s not on the web. I wonder if anyone has used the previous views and gone past the first few pages, unless it’s the author view to jump to a part of the alphabet. Think about the archetypal web application – Google. It uses search and faceted search (time, site, type of content etc). And how often do we, as users, go beyond a few pages? Web applications are about quickly finding content via a search or filters, or searching on something else. That’s also the way I’ve tended to build web applications and it’s the way I’ve built the first IDMA mobile application.

Yes, a search is harder to build. For this faceted search I finally used Java 8 coding to more easily build the full text search. Historically, there have been reasons people have avoided full text searches. They’re not necessarily up-to-date if data regularly changes. It doesn’t in OpenNTF Snippets and who’s likely to search for a snippet just created? Plus, the main page displays the most recent 15 snippets, when a search is not used. So why do we need to worry about that? Understanding the application, understanding the content is key to making the right decision. In my opinion, the right decision depends on context, depends on this application and should not be driven by a “one approach fits all” approach. But even if we did have to worry about most recent documents, we could look to update the server to Domino V10, which indexes up to 200 unindexed documents.

This approach, making design decisions based on the application in question, has also driven the display. This application doesn’t use a DominoView, a DocumentCollection or ViewEntryCollection. Instead, I’ve got a Java wrapper that wraps all the results into a LinkedList of Java objects. If you’re filtering just on an author or a language, I can just iterate over a ViewNavigator, which is quick. If it’s a search, it will do a full text search and iterate over the results. This means navigation through the pages is pretty quick, but means there is an impact on initial searches. But it means we can easily show the number of pages and don’t need to repeat the search. Yes, it may seem bad practice. But there are only 441 snippets in the system. That means we’re going to be collecting typically a handful of entries. So the code is easy and simpler to understand and the performance will not be noticeably bad.

Obviously that’s not going to work on a bigger dataset. But I have a variety of thoughts for how to worry about that. But if you want to see what the code would look like for those, then the community needs to add significantly more good snippets to the site! Of course one, when the server is upgraded to 10.0.1, is to change the full text search to DQL.

The home screen of “Recently Added” and “Most Downloaded (Last 3 Months) looks pretty similar, although (at the suggestion of one of the board members) I added a tooltip to show the description of the snippet. The aim is to use the screen real estate as much as possible. But of course tooltips are a good use case for a desktop browser, less so for mobile.

Beyond this page is again a significant difference between early XPages applications and my more recent applications. Previously the views used View Panels. Hopefully no one uses those now. There is no reason to use the very basic View Panel in preference to, at the very least, the Data View control or, in more advanced cases like this, a Repeat Control. They give a display better designed for the web and able to leverage more screen real estate and work better for responsive design.

At the top of the page, the “Create Snippet” button has been hidden unless logged in. The login area itself no longer redirects to the default server login page but instead is a panel that displays when the “Login” link is clicked. It also allows the ability to register and to trigger a forgotten password functionality. Of course that works great on a web application that allows anonymous access. If the application’s access is restricted as a whole, you need to make different design decisions.

In terms of some of the other links, they’ve been changed from being stored in a configuration document to being hard-coded in the design. That may seem like bad practice. And if the system was administered by end users who regularly reviewed everything, the choice of a configuration document would work. But those soft-codings didn’t stop links in the site being out of date and incorrect. It also meant they were harder to find with a search. If the links change in the future, DDE search will find them all easily. And the people administering the site are typically developers, so having them in the design doesn’t make it harder for them to find or update. Moreover it doesn’t matter that the links to terms and conditions etc point to the main OpenNTF site on dev, test and live. So for all those reasons, they were changed to be hard-coded rather than in a configuration document.

In the Snippet document itself, the order of the layout has been changed quite a bit. The buttons have also been styled. If you look at the classes assigned to them, you’ll see references to “primary”, “friendly” and “danger”. This and the colouring was driven by experience I had in Vaadin and best practices in a Vaadin webinar. It helps differentiate the buttons a bit better.

As I say, many of the decisions were driven might be different for different applications or different audiences. But in my opinion, that’s as it should be. It ensures the application design is appropriate to the application and only as complicated as needed. It also ensures development and maintenance is as quick as possible. And that’s what counts, particularly when we’re talking about an application built by volunteers and administered by volunteers, who have limited time and limited community help.

About The Author

Paul Withers is an IBM Lifetime Champion, has been an OpenNTF Board Member since 2013, has worked with Domino since R4.5, XPages since 2009, co-authored XPages Extension Library and was technical editor for Mastering XPages 2nd Edition. He is one of the developers on OpenNTF Domino API as well as contributor to a variety of other OpenNTF projects. For full bio, see https://paulswithers.github.io/professional/

1 thought on “OpenNTF Snippets – Investigating The Design”

Neat work Paul. I like to browse through them though to see what pops up of interest rather than specific searches when using this type of facility. I still think it would be better to have the ability to do that.

At Intec we collaborate with our clients, bringing together business insight, significant experience and technology to provide a distinct advantage in today’s rapidly changing business environment. Through our integrated approach to problem solving, solution design and execution we help turn our customers strategies into action. With over 30 years experience our mission is to help our customers to anticipate change and profit from new opportunities. The result of that experience and knowledge is a reputation for being trusted advisors and subject matter experts in a wide range of business and information technology areas.