Using XControls for developing cards-based UI for mobile and desktop applications

Introduction

For a project I reviewed several frameworks to deliver a web interface. Among them was XControls which is a project on OpenNTF. XControls promises to deliver:

  • Faster design and assembly of modern user interfaces, using Card & List objects.
  • Easy the auto-optimization for smartphones, tablets and PCs.

bc-ipad-contacts-framed

XControls is built with Bootstrap and the Bootcards project.

Bootcards

Bootcards is a cards-based UI and it is built on top of Bootstrap. Unlike most other UI frameworks, it includes a dual-pane interface for tablet users.

The documentation describes well the structure and options for the two main objects, card and list (analagous to Forms and Views in traditional Notes development).

Basically you have 2 types of list:

  • Normal.
  • Detailed.

Below is an example of the Detailed list:

bc-list-detailed

And 8 types of cards:

  • Base.
  • Form.
  • Table.
  • Chart.
  • Summary.
  • Media.
  • File.
  • Rich text.

Below is an example of the Media card:

card-media-ios

Bootstrap

Bootstrap claims to be the most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web. We will not introduce this framework further.

Getting started with XControls

Part of the documentation for XControls is the Getting started page which will walk you through creating a new application using XControls. I suggest to read this first and keep the primer documentation side by side.

Download the files

The required files can be either downloaded from OpenNTF or Github. Unfortunately XControls is not available as a plugin for your XPages development so you need to copy the required files manually in your existing project/NSF or you can use the provided NTF as a starter-kit for a new project.  The files are:

  • All custom controls starting with UnpBoot naming.
  • All Xpages starting with Unp naming.
  • All Resources\Files.
  • The”blank” theme (set this as application theme in XSP Properties file).

After that you are ready to develop the UI for your application! A recommended tip is to install the sampler application provided with the OpenNTF download and open that one in a browser and Domino Designer.

Test: Notebook/Journal

For my review I decided to apply the XControls methodology on a simple existing Notes application: the Notebook. This application allows you store simple documents which can combine rich text and file attachments. You are also able to ‘tag’ these documents by applying categories.

I will describe the steps taken to apply the XControls cards-based UI to this application.

Step: Copy the required files

The documentation does not describe to copy the unpCommon server-side javascript library.

Step: Create XPage unpMain

When creating an application, if it is going to be used on Teamstudio Unplugged mobile devices then we recommend that the home XPage is called UnpMain. Otherwise you are free to name your XPage.

Step: Add UnpBootResources

Every XPage that will be opened by the end-user needs the UnpBootResources custom control added. This adds CSS, JavaScript and Server Side JavaScript to your application.

<unp:UnpBootResources></unp:UnpBootResources>

Step: Create a common application layout

To provide a common application layout the Common Header and Common Footer custom controls should be included in the XPages that are accessible by the end-user.

Common Header

In case you want the app to develop for Mobile and Desktop then add a UnpBootNavigator and UnpBootHeader.

  • UnpBootNavigator: for mobile (the so-called ‘hamburger’ menu).
  • UnpBootHeader for desktop.

Also define the navitems in UnpBootHeader.

<unp:UnpBootHeader title=”${javascript:return @DbTitle()}”>
<unp:this.navitems><![CDATA[#{javascript:[
{label: “All Entries”, hasSubMenu: false, page: “/UnpMain.xsp”, icon: “fa-database”},
{label: “By Category”, hasSubMenu: false, page: “/vwCategory.xsp”, icon: “fa-list”},
{label: “By Entry Date”, hasSubMenu: false, page: “/vwEntryDate.xsp”, icon: “fa-calendar”},
{label: “Trash”, hasSubMenu: false, page: “/vwTrash.xsp”, icon: “fa-trash-o”}
]}]]></unp:this.navitems>
</unp:UnpBootHeader>

unpl_header

<unp:UnpBootNavigator>
<unp:this.menuitems><![CDATA[#{javascript:[
{label: “All Entries”, hasSubMenu: false, page: “/UnpMain.xsp”, icon: “fa-database”},
{label: “By Category”, hasSubMenu: false, page: “/vwCategory.xsp”, icon: “fa-list”},
{label: “By Entry Date”, hasSubMenu: false, page: “/vwEntryDate.xsp”, icon: “fa-calendar”},
{label: “Trash”, hasSubMenu: false, page: “/vwTrash.xsp”, icon: “fa-trash-o”}
]}]]></unp:this.menuitems>
</unp:UnpBootNavigator>

unpl_navigator

Font Awesome

Font Awesome gives you scalable vector icons that can instantly be customized – size, color, drop shadow, and anything that can be done with the power of CSS. XControls supports Font Awesome icons everywhere.

As you can see in the code above Font Awesome is for example used in the common header.

Common Footer

In case you want to include synch (for when running on Unplugged) add the UnpBootFooter as the common footer. You can also apply tabs in the footer if desired.

<unp:UnpBootFooter synctype=”none”>
<unp:this.tabs><![CDATA[#{javascript:[
{label: “Google”, hasSubMenu: false, page: “http://www.google.com&#8221;, icon: “fa-google”},
{label: “Like us”, hasSubMenu: false, page: “http://www.facebook.com/infowaresweden&#8221;, icon: “fa-facebook”}
]}]]></unp:this.tabs>
</unp:UnpBootFooter>

unpl_footer

 

Best practice tip

Since you will place the application layout just created across multiple XPages it is wise to store them in re-usable custom controls e.g. commonheader and commonfooter.

Step: Create the first content list

In the navigation we have declared that the initial XPage shall contain the All Entries overview. This overview simply lists the documents in a flat structure. You can use the UnpBootFlatView custom control for this.

Apply wrappers

To layout the content according to the bootcards definition apply a wrapper for the content:

<div id=”main” class=”container bootcards-container”>
<div class=”row fullheightrow”>
<!– add your list –>
<div id=”doccontent” class=”col-sm-7 bootcards-cards hidden-xs”>
<!– add your initial content e.g. a card–>
</div>
</div>

In the dual pane UI the target for dropping card content will be the div with ID doccontent.

Apply a list

<unp:UnpBootFlatView viewname=”($All)” summarycolumn=”$52″
numberofrows=”20″ newlink=”entry.xsp” xpagedoc=”UnpMain.xsp”
title=”All Entries” ajaxload=”Yes”>
</unp:UnpBootFlatView>

A description for all the available properties for the UnpBootFlatview can be read here: link. Property xpagedoc defines the xpage to load documents with, by default this would be the same as the current XPage.

Below is the result (only 2 documents in the database at the moment):

unpl_list

 

Below is the result when clicking on the Add link:

unpl_newentry

The XPage entry.xsp will be opened in a dialog. For now entry.xsp contains an unconfigured Form Editor custom control only. As you can see this requires more work.

 

 

Apply a Form Viewer

A Form Viewer is a wrapper that allows you to display document data inside a card. I created a custom control named docviewer and placed a UnpBootFormViewer inside it and configured it as followed:

<unp:UnpBootFormViewer editxpagewithajax=”yes”
formname=”JournalEntry” title=”Notebook Entry”
titleiconfield=”thumbnail” showbuttons=”true”
editxpagename=”entry.xsp”>
<unp:this.footertext><![CDATA[#{javascript:var id = context.getUrlParameter(“documentId”);
if (id != “”){
var doc:NotesDocument = database.getDocumentByUNID(id);
if (doc !=null){
var date = doc.getLastModified();
return “Last modified: ” + date
}
}}]]></unp:this.footertext>
<xp:this.rendered><![CDATA[#{javascript:context.getUrlParameter(“documentId”) != “”}]]></xp:this.rendered>
<xp:this.facets>
<xp:panel id=”list-group” xp:key=”facet_1″ styleClass=”panel”>
<div class=”list-group”>
<div class=”list-group-item”>
<label>Subject</label>
<xp:text id=”subject” tagName=”h4″ styleClass=”list-group-item-heading”>
<xp:this.value><![CDATA[#{javascript:docview.getItemValueString(“Subject”)}]]></xp:this.value>
</xp:text>
</div>
<div class=”list-group-item”>
<xp:label value=”Category” id=”lblCategory” for=”category”></xp:label>
<xp:text tagName=”h4″ id=”category” value=”#{docview.Categories}” styleClass=”list-group-item-heading”></xp:text>
</div>
<div class=”list-group-item”>
<xp:label value=”Date” id=”lblDate” for=”date”></xp:label>
<xp:text tagName=”h4″ id=”date” value=”#{docview.DiaryDate}” styleClass=”list-group-item-heading”></xp:text>
</div>
<div class=”list-group-item”>
<xp:label value=”Content” id=”lblCnt” for=”content”></xp:label>
<xp:text tagName=”h4″ id=”content” value=”#{docview.Body}” styleClass=”list-group-item-heading” escape=”false”></xp:text>
</div>
</div>
</xp:panel>
</xp:this.facets>
</unp:UnpBootFormViewer>

Again the entry.xsp is set to offer the document in edit mode (in a dialog). It appears that docview is the representation of the document. If you want to use data from the document outside the facet e.g. in the card footer you seem not to be able to refer to docview.

Below is an example of a selected document from the list:

list_docview

If you select Edit the document is presented in a dialog via XPage entry.xsp which is still empty. Let’s work on that one right now!

Apply a Form Editor

A Form Editor is a wrapper into which you can insert form fields for creating and editing documents. Fields can include auto clearing, type ahead, date pickers, numbers and rich text.

Below is the code that I included in the Xpage entry.xsp which is shown in dialog boxes when editing or creating a new document:

<unp:UnpBootFormEditor showbuttons=”true”
viewxpagename=”UnpMain.xsp” title=”Entry” formname=”JournalEntry”
footertext=”You can use your Notebook as a diary, to store meeting minutes or status reports, or simply as a place to create and store draft documents until they are ready for publication.”>
<xp:this.facets>
<xp:panel xp:key=”facet_1″ id=”list-group”>
<div class=”form-group”>
<xp:label styleClass=”col-xs-4 control-label” for=”subject” value=”Subject”></xp:label>
<div class=”col-xs-8″>
<xp:inputText id=”subject” value=”#{docedit.subject}” styleClass=”form-control required”>
<xp:this.attrs>
<xp:attr name=”placeholder” value=”Subject”></xp:attr>
</xp:this.attrs>
</xp:inputText>
<a href=”” class=”bootcards-clearinput”>
<i class=”fa fa-lg fa-times-circle”></i>
</a>
</div>
</div>
<div class=”form-group”>
<xp:label value=”Date” id=”datetime_dairydatelabel” for=”dairydate”
styleClass=”col-xs-4 control-label”>
</xp:label>
<div class=”col-xs-8″>
<xp:inputText id=”dairydate”
styleClass=”form-control”>
<xp:this.attrs>
<xp:attr name=”datevalue”>
<xp:this.value><![CDATA[#{javascript:try{
var date:lotus.domino.local.DateTime = docedit.getItemValueDateTime(‘DiaryDate’);
return date.toJavaDate().getTime();
}catch(e){
return new Date().getTime();
}}]]></xp:this.value>
</xp:attr>
</xp:this.attrs>
<xp:this.converter>
<xp:convertDateTime type=”date”
dateStyle=”short”>
</xp:convertDateTime>
</xp:this.converter>
</xp:inputText>

</div>
</div>
<div class=”form-group”>
<xp:label styleClass=”col-xs-4 control-label” for=”Categories” value=”Category”></xp:label>
<div class=”col-xs-8″>
<xp:inputText id=”Categories” value=”#{docedit.Categories}” styleClass=”form-control required”>
<xp:this.attrs>
<xp:attr name=”placeholder” value=”Category”></xp:attr>
</xp:this.attrs>
</xp:inputText>
<a href=”” class=”bootcards-clearinput”>
<i class=”fa fa-lg fa-times-circle”></i>
</a>
</div>
</div>
<div class=”form-group”>
<xp:label value=”Content” id=”biolabel” for=”content” styleClass=”col-xs-4 control-label”>
</xp:label>
<div class=”col-xs-8″>
<unp:UnpBootRichTextEditor fieldname=”Body”></unp:UnpBootRichTextEditor>
</div>
</div>
</xp:panel>
</xp:this.facets>
</unp:UnpBootFormEditor>

Notes:

  • For the viewxpagename property I have chosen the UnpMain.xsp Xpage, this is the XPage to open after saving the document. Normally this would be the same as the current XPage.
  • The date field is bound to a date-picker.
  • For the rich text field I included a UnpBootRichTextEditor custom control. This will give the field some edit options.

Below is an example of the result. As you can see I did not at so many bells & whistles to the form editor (yet) to improve usability:

unpl_newentrydate

Step: Create the categorized content list

Can you imagine a Notes application without a categorized view? Probably not. In XControls you seem to have 2 options:

  • A flat list.
  • An accordion list.

A flat list for categorization, really? If you bind the UnpBootFlatView custom control to a categorized view as in the example below, the categorized view will be displayed as a flat list, but with documents/entries grouped in the provided categories:

<unp:UnpBootFlatView title=”Entries By Category”
summarycolumn=”$52″ viewname=”By Category” numberofrows=”20″
ajaxload=”Yes” detailcolumn=”$44″ xpagedoc=”vwCategory.xsp”
newlink=”entry.xsp” footertext=”A Flat List but with Categories :-?”>
</unp:UnpBootFlatView>

Below is an example of the result:

unplflatlistcategorized

Accordion list

However, if you want to apply a collapsible Notes-a-like feature, you can choose the UnpBootAccordion custom control to provide an Accordion list.

<unp:UnpBootAccordionView title=”Dates” summarycolumn=”$39″
viewname=”By Diary Date” expandfirstcategory=”no” ajaxload=”Yes”
loaddocumenttarget=”doccontent” detailcolumn=”$44″
xpagedoc=”vwEntryDate.xsp” newdatatarget=”#editModal”
newlink=”entry.xsp”>
<unp:this.footertext><![CDATA[#{javascript:var date = @Date(@Today());
return “Today is: ” + date.toDateString()}]]></unp:this.footertext>
</unp:UnpBootAccordionView>

Below is an example of the result:

unplaccordion

The ‘categories’ are collapsible. Note that I had to modify the column value for the date: @Text(DiaryDate).

unplaccordioncollapsed

Summary

So far my initial review took. It seems fair enough to say that XControls enables you to deliver a dual pane cards-based UI for your Notes application without too much amount of development time.

I did explore many other features the framework offers (calendaring, carousels, charts) but it is definitely an OpenNTF project to keep an eye on. Especially if you are not capable of running a full blown solution like Worklight or you want to test early feedback for delivering existing Notes applications to mobile devices.

3 thoughts on “Using XControls for developing cards-based UI for mobile and desktop applications

  1. steven podrouzek 2015-January-9 / 2:57 pm

    Also looked at this, but was wondering if I could convert some seriously big applications to this framework. The journal database is easy, but would this work with other serious Domino applications? What do you think? Would it not be easier to just use standard XPages with the mobile framework, and some java?!

    • Patrick Kwinten 2015-January-11 / 9:08 pm

      Hi Steven,

      you are right, the Journal database is a lightweight example.

      I can not tell how ‘serious’ your application is.

      I assume you can tie a lot of client side javascript to the save action but then if you tie so much cs javascript why do you not converge to a full cs javascript application and leave xpages behind?

      I guess the ones who can best answer on your question are the creators of the xcontrols framework?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s