202 Lotus blogs updated hourly. Who will post next? Home | Blogs | Search | About 
Latest 7 Posts
Minor enhancements to the XPages Table Control
Wed, Dec 13th 2017 124
XPages JDBC Configuration via NotesDocuments
Tue, Dec 5th 2017 33
My New Approach for Sharing XPages Controls and Extensions
Fri, Dec 1st 2017 18
Embedded Experiences not rendering after IBM Notes FP9
Wed, Sep 27th 2017 5
BuildXPages Deployment Automation Tools – v1.0.0
Thu, Sep 21st 2017 8
Generating and Downloading Files Using XPages’ Persistence Service
Wed, Sep 13th 2017 6
Bundle Inspector – Diagnosing XPages Plugin Resolution problems
Wed, Aug 2nd 2017 7
Top 10
Minor enhancements to the XPages Table Control
Wed, Dec 13th 2017 124
XPages JDBC Configuration via NotesDocuments
Tue, Dec 5th 2017 33
My New Approach for Sharing XPages Controls and Extensions
Fri, Dec 1st 2017 18
Preventing Pasting of Images in CKEditor
Mon, Nov 14th 2016 13
Preventing pasting of remotely hosted images in CKEditor
Mon, Nov 14th 2016 11
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 11
Controlling the order of Script Resources (e.g. Jquery) with a Custom ViewRootRenderer
Mon, Sep 19th 2016 9
Build System for XPages and OSGi plugins
Fri, Aug 8th 2014 8
Webmail UI – You must learn about MIME
Wed, Apr 20th 2016 8
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 8

Markdown XPages UIControl
Twitter Google+ Facebook LinkedIn Addthis Email Gmail Flipboard Reddit Tumblr WhatsApp StumbleUpon Yammer Evernote Delicious

Often when I’m designing an xpage, there might be a section of the page in which I want to explain some instructions to the user. Some options here are to:

  1. write the Instructions using html and embed directly in the xpage markup
  2. write the Instructions directly in the design pane and format using designer’s ui e.g. bold, color, size etc
  3. use some native xpage controls to achieve the desired result.
  4. Write the instructions in a richtext field on a notes document that is loaded to display the info.

Option 1 works good but is annoying to type html opening and closing all those tags. Option 2 is quick to use but creates ugly html with hardcoded styles / colours etc. Option 3 is doable but still a little clunky, Option 4 is not a great move because it is very hard to include the instructions within source control.

A better option needed

Lightweight markup languages are a great way to let formatting ‘get out of the way’ and just let you focus on writing the content. There are many lightweight languages to choose from. Markdown is a popular one so I thought that would be great to be able to quickly write some markdown and let the formatting take care of itself.

If you aren’t familiar with the concept, it is basically a system of writing some plaintext content that can automatically be converted to html. For example the following text is plain text but easy to see the intended structure:

This is a heading

This is a paragraph

* this is a list item
* this is another item

This will processed by Markdown into the following html

<h1>This is a Heading</h1>
<p>This is a paragraph</p>
<li>this is a list item</li>
<li>this is another item</li>

Side note: Asciidoctor is good too

I have also created a similar control for AsciiDoctor which is another lightweight format. I actually prefer to use Asciidoctor now, however since Markdown seems to be more common I thought I would share the markdown control first.

If you are interested in AsciiDoctor control let me know. It is a bit more intense though because it starts up a JRuby instance and maybe that is not something you’d like to do (because AsciiDoctor is ruby based).


A few years ago Martin Rolph from Oval UK shared a solution of a Markdown Custom Control. You can find the project on github at OvalUK/XPagesDemos. The solution used markdown4j which is a java-based markdown processor. I decided to build on Martin’s work and convert it from a custom control into an XspLibrary Control with a few extra options of where to retrieve the markdown from.

The markdown control allows you bind to a dynamic data source such as a NotesDocument / scoped variable etc. but also provides some options to load the source text from some static locations. You can have the source text:

  • Bound to a String Field in a Datasource or Scope variable
  • Supplied from a text file in the WEB-INF directory (read only)
  • Supplied from a text file from within a plugin (read only)
  • Supplied from a File in the ‘Resources’ Design Element (read only)
  • Written directly within the control’s start and end tags (passthrough text) but this has some gotchas. (read only)

The control is an extension of the normal ‘inputTextArea’ control. When the control is in edit mode it just works exactly like a plain text area.

In Read-only mode, the supplied plaintext will be converted to html for display using the Markdown Processor.

Simple Example

In this simple example, I am binding the text to a viewScope variable ‘sampleText’
I have 2 markdown controls, one on the left in edit mode, and one on the right in read mode, showing a live preview of the markup using the onKeyUp event to refresh the preview control. Here is the markup for the page

<h2>Live Preview example</h2>

<xp:table id="tablePreview" style="width:800px;margin-bottom:50.0px;margin-top:10.0px">
		<xp:td style="width:50%" valign="top">
			<gb:markdown id="markdown2" value="#{viewScope.sampleText}">
				<xp:eventHandler event="onkeyup" submit="true" refreshMode="partial" refreshId="markdown3" execMode="partial" execId="tablePreview"
		<xp:td valign="top">
			<gb:markdown id="markdown3" value="#{viewScope.sampleText}" readonly="true"></gb:markdown>

And here is an example of how it looks

Examples of the different methods of supplying the text

You should be able to find the control in the Controls palette under Gregorbyte Library. Drag it onto the page.

Bound to a Datasource / Managed Bean

You can bind it to any text field just like you would normally. In this example it is bound to a document and in edit mode acts just like a normal text area.

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

		<xp:dominoDocument var="document1" formName="Markdown"></xp:dominoDocument>

	<xp:button value="Save" id="button1">
		<xp:eventHandler event="onclick" submit="true" refreshMode="complete">

	<gb:markdown id="markdown1" value="#{document1.markdownText}"></gb:markdown>


Then in edit mode:

In Read only mode:

Supplied from WEB-INF

To read a file from WEB-INF the ‘value’ should be the path to the file

  • It must start with ‘/WEB-INF’
  • It must finish with ‘.md’
  • readonly property should be ‘true’


<!-- Read from WEB-INF -->
<gb:markdown id="markdown4" readonly="true" value="/WEB-INF/markdown/Sample.md"></gb:markdown>

Supplied from a File in the Resources Design element

To supply the text from a File in the Resources Design element, give your file should the .md extension, and then supply ‘value’ as ‘/<yourfilename>.md’, also set readonly=”true” e.g.

<!-- Read from the File Resources -->
<gb:markdown id="markdown1" readonly="true" value="/FileResource.md"></gb:markdown>

Supplied from a TextFile in a plugin

To supply the text from a file in a plugin, make sure your file has .md extension. Right click on the file in eclipse and ‘Copy Qualified Name’. Paste this as the ‘value’ and set readonly = true.
You may run into some trouble if your file is not included in the build process, or it is built to a different location than it is in the source code, but basically the format should be ‘/com.your.plugin/your/classpath/to/resource/file.md’

<!-- Read from A plugin -->
<gb:markdown id="markdown6" readonly="true" value="/com.gregorbyte.xsp/resources/sample/Markdown.md"></gb:markdown>

Written directly within start and end tag

This is a quick and dirty method but it is a bit buggy. If you sometimes format your xsp markup with Ctrl + Shift + F then it will ruin your markdown with indents etc. The markdown text must be placed flush with the margin of the code editor

<gb:markdown id="markdown5" readonly="true">
This text is directly within the tags 

It has some drawbacks though

* The text must be lined up directly against the margin (No indents) 
* If you hit 'Ctrl + Shift + F' to format your xsp markup, it will indent the text and ruin everything 
* You cannot embed html tags in the text

These bugs could be fixed but I just haven't got to it yet


To install you do one of the following:

  • install my GregorbyteXspLibrary to your designer + server
  • Scavenge necessary files from the Github repo

Method 1: Install my library

Go to the latest releases of camac/GregorbyteXspLibrary, download the zip file and install the update site using your favourite methods (same method as you would install IBM Extension Library)

Method 2: Scavenge Necessary files from github repo

You will need These java files

  • /com.gregorbyte.xsp.controls/src/com/gregorbyte/xsp/component/markdown/UIMarkdown.java
  • /com.gregorbyte.xsp.controls/src/com/gregorbyte/xsp/renderkit/markdown/MarkdownRenderer.java

You will need this JAR

  • /com.gregorbyte.lib.markdown4j/lib/markdown4j-2.2.jar

You will need this xsp-config (place in your WEB-INF

  • /com.gregorbyte.xsp.controls/src/com/gregorbyte/xsp/config/gregorbyte-markdown.xsp-config

You will need to include the contents of this file in your WEB-INF/faces-config.xml file

  • /com.gregorbyte.xsp.controls/src/com/gregorbyte/xsp/config/gregorbyte-markdown-faces-config.xml

I am pretty sure that is all that is needed, let me know if you have any trouble.


Once again thanks to Martin Rolph for providing the markdown custom control in the first place, I have simply added a few more ways to supply the source and wrapped it in a control.

I’d love to hear what you think if this is useful to you or not. Personally I have been using it mainly to supply markdown from within a plugin. Mainly help/instructions/code examples in our demo database.

Mar 05, 2017
4 hits

Recent Blog Posts
Minor enhancements to the XPages Table Control
Wed, Dec 13th 2017 10:44a   Cameron Gregor
As mentioned in my previous post, I have started up a fork of the ExtLibX project and have started contributing to it instead of my previous GregorbyteXspLibrary. Last week I shared the JDBC Configuration Provider which uses Notes Documents to store the configuration info,  within this release was another small contribution with 2 minor enhancements for the XPages  table control. The core XPages table control does not provide support for thead, tbody, and tfoot elements. Also there isn’
XPages JDBC Configuration via NotesDocuments
Tue, Dec 5th 2017 11:34a   Cameron Gregor
If you have used the Extension Library’s Relational controls, then you are probably familiar with the process of configuring your JDBC Connection details. You have the option of setting up a ‘named’ connection so you can reference a database connection by name. This involves creating an xml file .jdbc in the WebContentWEB-INFjdbc directory. This xml file specifies the driver, url, username, password, and perhaps some information about connection pooling. Alternatively your can
My New Approach for Sharing XPages Controls and Extensions
Fri, Dec 1st 2017 12:33p   Cameron Gregor
Over the past few years I have shared a handful of controls and techniques on my blog, and most of these I have made available on github in one way or another. Originally I was creating a separate github project for each one such as EmailValidator, PhoneNumberControl and the Messages Controls. After these few I decided it would be more efficient to create a single project that I could put them all into, so I then began to contribute them via my GregorbyteXspLibrary. From time to time I had a fe
Embedded Experiences not rendering after IBM Notes FP9
Wed, Sep 27th 2017 5:36a   Cameron Gregor
Embedded Experiences are no longer rendering after upgrading to FP9. I suspect it is something to do with the changes to Embedded Browser, either removing it or upgrading it or something else. I haven’t had a chance to investigate fully. Perhaps there may be a workaround, or perhaps this is specific to the way we are using embedded experiences. We use embedded experiences quite a bit at our company so we have rolled back for now. If I figure anything out I will post an update but just be a
BuildXPages Deployment Automation Tools – v1.0.0
Thu, Sep 21st 2017 12:47p   Cameron Gregor
After quite a bit of work I have finally published the first release of BuildXPages! What is BuildXPages? BuildXPages is a project which is useful if you are interested in Automating tasks that are involved in building XPages. For example you may be interested in automating some of these tasks: Building NSFs from an On-Disk Project Building Plugins and Features Refreshing NSF Designs Setting Template Inheritance of NSFs Start, Stop and Restart Http server Uploading Plugins to an NSF Update
Generating and Downloading Files Using XPages’ Persistence Service
Wed, Sep 13th 2017 4:42p   Cameron Gregor
When developing an XPages application you may run into the need to generate files to be downloaded by the user. For example: Generating a PDF Report Exporting Data to Excel Spreadsheet Creating a Zip File of several attachments Achieving these tasks usually raises 2 main problems to solve; What temporary place can I use to generate the files? How do I allow the user to download the generated files? For the temporary place problem, some common solution is to either generate the files to some
Bundle Inspector – Diagnosing XPages Plugin Resolution problems
Wed, Aug 2nd 2017 12:26p   Cameron Gregor
A common task with XPages development is to installing some plugins that provide additional functionality. If you do any plugin development of your own, you end up doing this task a lot more as you create new plugins, install new versions etc. It is also common to encounter some problems after installing plugins to your Domino Server! Maybe your expected plugin doesn’t load up at all? maybe the wrong version is loading? The standard method of diagnosing these problems is to use the OSGi c
Swiper Official Version 2 Release
Fri, Jul 21st 2017 1:52p   Cameron Gregor
So I have finally posted Swiper version 2 to OpenNTF! (and Github of course) Swiper OpenNTF Project Page Swiper Github Releases The latest version is 2.0.1,  and is the same as 2.0.0beta but with a bug fix for the toolbar buttons. Swiper 2.0.0 beta has been available on the Github project site for a few months, and the core functionality of it works as planned. There was however a bug within the shortcut buttons that I added to the menu bar, and this is a bit of a nasty bug that can cause del
Auto-width Bootstrap Column XPages Controls
Tue, Mar 21st 2017 1:13p   Cameron Gregor
I’ve been stuck working with OneUI Version 3 for the past couple of years, due to a regretful decision made at the beginning of my major project. OneUI was better than nothing but very frustrating at times. Finally, I have moved on to my next project and I am now using bootstrap (version 3) A common task when laying out a page using bootstrap is to divide sections up into rows and columns, and use the appropriate css styles to do so. I’m going to assume you are familiar with bo
Swiper FP8 Version Beta Release
Thu, Mar 16th 2017 12:50p   Cameron Gregor
Last week I released the ‘alpha’ version of Swiper which was untested on FP8 but presumed to be ok. So far I have only had good reports from the pioneers who have gone ahead and installed FP8 + the alpha version. I have since managed to ugrade my home office setup to FP8 which unfortunately has broken my ability to launch designer from eclipse but I am seeking some advice on fixing this up. In the meantime I have to test the slow way of building plugins, import plugins, restart R

Created and Maintained by Yancy Lent - About - Planet Lotus Blog - Advertising - Mobile Edition