199 Lotus blogs updated hourly. Who will post next? Home | Blogs | Search | About 
 
Latest 7 Posts
Auto-width Bootstrap Column XPages Controls
Tue, Mar 21st 2017 4
Swiper FP8 Version Beta Release
Thu, Mar 16th 2017 9
Swiper FP8 Integration Rollout
Wed, Mar 8th 2017 6
Markdown XPages UIControl
Sun, Mar 5th 2017 5
TextDiff XPages control – For visual comparison of text
Tue, Feb 28th 2017 4
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 9
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 10
Top 10
Tips for Creating a Webmail UI with XPages
Tue, Apr 19th 2016 12
Webmail UI – You must learn about MIME
Wed, Apr 20th 2016 11
XPages PhoneNumber Control - Part 1 Creating a Converter
Wed, Feb 18th 2015 10
Controlling the order of Script Resources (e.g. Jquery) with a Custom ViewRootRenderer
Mon, Sep 19th 2016 10
Preventing Pasting of Images in CKEditor
Mon, Nov 14th 2016 10
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 10
Build System for XPages and OSGi plugins
Fri, Aug 8th 2014 9
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 9
Swiper FP8 Version Beta Release
Thu, Mar 16th 2017 9
Inspect Component Properties using Component Binding
Tue, Mar 8th 2016 8


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

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>
<ul>
<li>this is a list item</li>
<li>this is another item</li>
</ul>

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

Overview

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:tr>
		<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"
					disableValidators="true">
				</xp:eventHandler>
			</gb:markdown>
		</xp:td>
		<xp:td valign="top">
			<gb:markdown id="markdown3" value="#{viewScope.sampleText}" readonly="true"></gb:markdown>
		</xp:td>
	</xp:tr>
</xp:table>

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:this.data>
		<xp:dominoDocument var="document1" formName="Markdown"></xp:dominoDocument>
	</xp:this.data>

	<xp:button value="Save" id="button1">
		<xp:eventHandler event="onclick" submit="true" refreshMode="complete">
			<xp:this.action>
				<xp:saveDocument></xp:saveDocument>
			</xp:this.action>
		</xp:eventHandler>
	</xp:button>

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

</xp:view>

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’

e.g.

<!-- 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
	</gb:markdown>

Installation

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.

Conclusion

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.



---------------------
http://camerongregor.com/2017/03/05/markdown-xpages-uicontrol/
Mar 05, 2017
6 hits



Recent Blog Posts
4
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
9
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
6
Swiper FP8 Integration Rollout
Wed, Mar 8th 2017 12:43p   Cameron Gregor
Notes Domino 9.0.1 FP8 is finally here and as far as I know (I have yet to download it) it includes the necessary changes which will allow Swiper to swipe whatever it wants, whenever it wants, which is good news for people who don’t like to have ‘Build Automatically’ turned on. Plan of Attack for release of Swiper version 2.0.0 So, I haven’t actually downloaded FP8 yet,  so I can’t say for sure that the updated version works perfectly. Here is a bit of backgrou
6
Markdown XPages UIControl
Sun, Mar 5th 2017 11:44a   Cameron Gregor
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: write the Instructions using html and embed directly in the xpage markup write the Instructions directly in the design pane and format using designer’s ui e.g. bold, color, size etc use some native xpage controls to achieve the desired result. Write the instructions in a richtext field on a notes document that is loaded to dis
4
TextDiff XPages control – For visual comparison of text
Tue, Feb 28th 2017 12:00p   Cameron Gregor
A few years back I stumbled across Google’s diff-match-patch project which provides some handy algorithms for text manipulation. At the time of discovery I was doing ‘classic’ notes development. Although I probably could have implemented something that worked in lotuscript with RichText or Mime, it wasn’t a priority at the time and I never bothered. Since then, I have been doing mainly XPages, and now that I have been also doing a bit of XPages Control development. I was
9
XPages webmail – Using Mime Inspector to debug Mime
Tue, Feb 14th 2017 11:12a   Cameron Gregor
In a previous post in this series I did a bit of an overview on how MIME works. We also did a little bit about how MIME works in XPages + Domino land. With this knowledge in hand we can now start to analyse the different ways a ‘Pretty words, pictures and attachments’ can be stored in the document. During development of the ‘XPages Webmail’ interface, I encountered many problems which could only be solved by investigating the MIME content in detail. To help me do this, I
10
Pasting Images into XPages CKEditor
Sun, Feb 12th 2017 10:00p   Cameron Gregor
Programs like ‘Snipping Tool’ on Windows, are super useful for users to make a quick snapshot, do some quick markup on the image, paste into chat/email and send. Unfortunately when using the default configuration of CKEditor in XPages (the inputRichText control), support for pasting images is not available for all browsers, and even for the ones that do support it, the images are only pasted as a PNG data URI. I have explained data URI images in a previous post, so check that out if
8
Preventing pasting of remotely hosted images in CKEditor
Mon, Nov 14th 2016 11:21p   Cameron Gregor
In the previous post, I showed how to prevent a user from pasting Images from the Clipboard into CKEditor. This post is of a similar nature but is designed to ensure that users don’t paste images with URLs to external / internal applications. This post is part of my XPages webmail tips series, and addresses a problem where, a user copies and pastes some HTML that includes images, from a webpage and pastes it into CKEditor for a message that is then sent via email. The recipient is then una
10
Preventing Pasting of Images in CKEditor
Mon, Nov 14th 2016 12:43a   Cameron Gregor
In the process of developing our XPages ‘Webmail’ interface, we discovered that many recipients were unable to view embedded images in the emails. After investigating, it was caused by the images being embedded using Data URIs. Support for Data URI Images is not universal, and because it is supported in IBM Notes, everything looked like it was working ok, but a quick test viewing an email in Gmail confirmed a problem when images could not be seen. What is a Data URI? You are most lik
10
Controlling the order of Script Resources (e.g. Jquery) with a Custom ViewRootRenderer
Mon, Sep 19th 2016 9:28a   Cameron Gregor
When loading Client Side Javascript libraries in XPages, sometimes the order that the libraries are ‘encoded’ (or written in HTML) in the tag is important. For example jQuery and some of it’s plugins can have some issues if Dojo is encoded first. By default in XPages you don’t have too much say in what is written out first, a nifty workaround for this has been shared by Sven Hasselbach (here and here) which utilises the lesser known tag. This workaround ensures t




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