Anatomy of a UI Control - Extension Library Case Study

Anatomy of an XPages UI
Control
Cameron Gregor | Systems Developer
Jord International
www.jord.com.au
Blog: camerongregor.com
Twitter: @gregorbyte

March 10th & 11th, Sydney, AustraliaMeet.Share.Learn.Connect @AusLUG #@Inform2016

Goals of this Session
• Spark some curiosity in Control Development + ExtLib
• Provide a ‘Signpost’ for navigating Extension Library Code
• Demonstrate how to develop / debug / deploy controls

Understanding
• Recognising
common patterns
• Gain Familiarity
• Diagnose own
Problems
Modifying
• Bug fixes
• New Behaviour to
Existing
• Finishing Incomplete
features
Creating
• New Controls
• New Services
• New Utilities
• New Themes

Agenda
● Identify the ‘Elements’ of a UI Control from the Extension Library
● Getting set up to explore the Source Code of Extension Library
● Techniques on Exploring Source Code within Eclipse
● Demonstrate how we locate the Source Code of our ‘Elements’
● Some Examples of Extending / Modifying / Creating UI Controls

Terminology I might used Interchangeably
Component = Control = UI Control = UI Component
Plugin = Project
Control != Custom Control

Anatomy – Identifying the Moving Parts
• Design Time
– Palette Entry
– Mark-up Tag Details
– Visualisation
– Component Metadata
• Class Name
• Properties
– Property Panels
– Drop Action
• Runtime
– Component Behaviour
– Renderers
• Default Renderer
• Renderers for Other themes
– One UI 2
– One UI 3
– bootstrap

Design Time Properties
• MOSTLY specified in xsp-config
• SOME can be specified through Extension Points

Palette Entry
• Should Show in Palette?
• Category
• Description
• Icon

Markup Tag Details

Visualisation
• What should it look like in Design Tab?

Component Properties
• What Properties can be set?
• How can they be set?
– “” – Literal?
– “${}” – Page Load?
– “#{}” – Compute Dynamically?
– Is it a list of things?
• Drop down Nodes
– What Type?

Property Panels
• Make a big difference in usability
• If well designed, reduce
the need for Documentation

Drop Action

Component Behaviour
• How does it operate?
• Any special behaviour? E.g. dialog.show();
• For Input Controls, does it have default Validators, Converters?
• Is it an AJAX Component?
• Is it Themeable?

Runtime - Renderers
ONE UI V2 ONE UI V3 BOOTSTRAP

PREPARATION

Setting Up To Explore
• Download Eclipse
• Download XPages SDK
• Download Extension Library Source Code
• Import Extension Library Projects to Eclipse
• Configure Eclipse with XPages SDK
• Slides covering this setup are in the Appendix! Download from Auslug after the
conference
– I will also put them up on my blog / slideshare

EXTENSION LIBRARY
STRUCTURE

41 Projects?
Where to Start?
Let’s narrow our focus
• 3rd Party Library Projects
• Feature Projects
• Test Projects
• Domino Access Services
projects
Make some more
Working Sets

Identifying 3rd Party Library
• In normal Java, JARs are just added
to the classpath
• For OSGi development, a plugin
‘wraps’ the jar and provides classes
via the plugin framework
• These ‘wrapper’ plugins can usually
be identified as only having one or
more jar files in them

Feature Projects
• Contain feature.xml
• Often Project name ends in ‘feature’
• Only used when ‘packaging up’ the plugins
• These are BORING let’s get them out of the way
– We didn’t even need to import them in the first place, I just wanted to keep that step
simple
• We can Delete from our eclipse ‘workspace’

Delete the feature projects
• Select all the feature projects
– The one’s on the left are the ones I did
• Press ‘delete’
• No Need to ‘delete contents on disk’

Test Plugins
• Used by developers during development to run ‘unit tests’ and what not
• We don’t really care at this point
• Let’s get them out of the way

Domino Access Service Projects / REST
• Used for DAS
• Look at them if you are interested!
• We are focussing on Xpages Controls, so we don’t care
• Lets put them in a Working set of their own

These ones have all the ‘smarts’
and used during actual Xpages
runtime
These ones have extra
‘tooling’ information
For Domino Designer to use
These ones aren’t of too
much interest to us
9 Main Plugins
5 Designer Only Plugins

Main Control Library Plugins
com.ibm.xsp Description
.bluemix.util New classes for use of Xpages in ‘Bluemix’
.extlib Contains the ‘XspLibrary’ that you enable for your NSF, all other
plugins exposed through this one, not too much to look at though.
.extlib.controls The main Controls project with Components, default
renderers, xsp-config files, and faces-config.xml files.
*We are mainly interested in this one*
.extlib.core Contains Utility functions that are used by all other extlib plugins
.extlib.domino Any Controls SPECIFIC to domino go in here.
E.g. DynamicView, DominoNAB Value Picker etc.
.extlib.mobile All the mobile controls. Not sure if many ppl use these?
.extlib.oneui All the OneUI themes, resources, renderers, app layouts
.extlib.relational Code related to the Relational Database Access functionality
.theme.bootstrap All the Bootstrap themes, resources, renderers, app layouts

Designer Tooling Plugins
com.ibm.xsp.extlib Description
.designer Just some utility classes used by the tooling
.designer.bluemix All the new bluemix configuration and deployment tooling. Might
be interesting to look into but not for our purpose here
.designer.relational Tooling for JDBC Plugin Generator (Can be used to wrap JDBC
Drivers into a plugin for relational db access)
.designer.tooling Additional Tooling information for the Extension Library
controls
.designer.xspprops The ‘xsp.properties’ editor comes from here. Interesting to look at
but not for our purpose

Interesting to us for our ‘WidgetContainer’ Investigation
3 ‘Normal’ Projects
• com.ibm.xsp.extlib.controls
• com.ibm.xsp.extlib.oneui
• com.ibm.xsp.theme.bootstrap
1 Designer Tooling Project
• com.ibm.xsp.extlib.designer.tooling
Much simpler than 41 Projects!

DISCOVERING THE SOURCE

Eclipse Shortcuts and Tips
Ctrl + Shift + T Find a Java Class by Name
Ctrl + Shift + R Find a Resource by name (XML file, image, text file etc.)
Search -> File Search Contents of files
Search -> Java Search Java types fields etc
Right Click -> References Find out where else that thing is used
Ctrl + Click Click through to the Definition of that thing
F4 Open Type Hierarchy – Navigable Help on that Hierarchy
Ctrl + T Quick Type Hierarchy (Tooltip help)
Ctrl + O Quick Outline of current class (jump to method / field)

Where to Start?
• Thought Process:
– Let’s find the Design Time Properties first
– Design time Properties will be in an .xsp-config file somewhere
– Those Properties should include the tag name
– We know it’s tagname is ‘widgetContainer’
– Let’s search for text ‘widgetContainer’ in *.xsp-config files

Eclipse Shortcuts and Tips

File Search

Scope Searches
Workspace All projects in the workspace
Selected Resources Whatever is selected in the Package Explorer (and children)
Enclosing Projects Search within the projects of the selected things
Working Set Just search within a Working Set (ExtLib, ExtLib Designer etc.)

2 Files? Which one is correct
• Domino Designer actually uses the one without ‘raw’ prefix
• IBM Use the ‘raw’ one to generate the real one + localised properties

Difference between raw- and normal
Raw file has English descriptions, easier to read for source code browsing
Generated file has English descriptions replaced with localisation placeholders to
allow for other languages

Find extlib-containers.xsp-config file
Jumps to

Commonly seen together
English Localisation Properties
Runtime Configuration
Design Time Configuration
raw-extlib-containers.xsp-config down with the R’s

Looking for the Design Time Elements
Things we can find in xsp-config
• Design Time
– Palette Entry
– Mark-up Tag Details
– Visualisation
– Component Class
– Component Properties
– Property Panels
– Drop Action

Other Details we look for in <component-extension> tag
• Find the <component> that relates to the widgetContainer
• Look for <component-extension> tag within that
Default Namespace and Prefix
• Usually at the Top of the
xsp-config file

<component-extension>
Tag Name
Palette Details
No mention of Icon though?
Visualization
BUT this one is commented out,
so where is it coming from?

Component Java Class
• Find the <component> tag for the WidgetContainer
• Find the <component-class> tag underneath that

Component Properties
• Find <component> tag for WidgetContainer
• Look at all the <property> tags beneath that

Component Properties – Group Type Reference
• Component may refer to previously defined groups of properties that are
common amongst many Components

How are we going?
• Design Time
– Palette Entry - Found but no Icon?
– Mark-up Tag Details - FOUND
– Visualisation – Found but commented out?
– Component Class - FOUND
– Component Properties - FOUND
– Property Panels
– Drop Action
Where is the Remaining info? Let’s expand our search to all file types

Search all files for widgetContainer

Lots of matches
After some digging amongst results…

Visualizer
• Visualization can be from xsp-config OR from a special Visualizer class
• Most of the Extension Library controls use a Visualizer class

Visualizer Markup example

What is in plugin.xml in the designer.tooling project?

Entry in tooling plugin.xml
Palette Details
Where are these icons?
Let’s use Find Resource

Finding a Resource
• Ctrl + Shift + R

Drop Action
• If the Component has a ‘Drop Action’ then this will be under the paletteItem

Entry in tooling plugin.xml
Panel Details

Custom Panel Example

How are we tracking
• Design Time
– Palette Entry - FOUND
– Mark-up Tag Details - FOUND
– Visualisation – FOUND
– Component Class - FOUND
– Component Properties - FOUND
– Property Panels - FOUND
– Drop Action - FOUND

Discovering Runtime Elements
• Runtime
– Component Behaviour
– Renderers
• Default Renderer
– One UI 2
– One UI 3
– bootstrap

Ctrl + Shift + T
• Launches the ‘Open Type’ dialog
• Search for part of the class name it prompts with some matches

UIWidgetContainer Class
• Most Component
class names start
with UI, e.g
UIWidgetContainer
UIDialog
• This is the real
‘brains’ of how the
control works and
the options it can
have
• Clues on how the control
interacts with the Xpages
system and page lifecycle

Component - Property Getter Setter pattern
• Common pattern used to enable ‘dynamically computed’ properties
If property was set with literal value e.g. “3”,
or on page load “${some.value}”,
return that value
Otherwise if it was specified as
Dynamically computed value
“#{some.value}”,
Compute it, and return that value
Setter is used to set the property when it was specified as literal value e.g. “3”
or a computed on page load “${some.value}” once and then stores it

Component - State Saving Pattern
• Between requests, the Xpages runtime MAY need to save the control’s state
• It asks the control for a state ‘object’ using the saveState function
• Function should return some object which contains all the properties to save
• Usually uses an Object array [] so it can contain mixed types

Component - Restore State Pattern
• When Xpages runtime re-creates a component tree, will ask the component to
‘restore itself’
• Xpages runtime gives the component the same state ‘object’ back that the
saveState function gave to it to save
• Component can then place
all the properties back in
there fields, ready to use
during the execution of the
Xpage

Does our Component inherit properties/behaviour?
• We can investigate with some shortcut keys

Ctrl + T
• Quick Tooltip overview of the currently selected Java Type’s hierarchy

F4
• More Interactive Hierarchy
• Navigate through the hierarchy
• Filter / sort fields methods etc.

Source not Found
• Just a class that is part of the core platform
– you don’t have Source code for – yet 

Renderers!
• Most likely the first thing you might Dabble in
– Oliver Busse NotesIn9
• http://www.notesin9.com/2015/04/20/notesin9-174-getting-started-with-custom-
renderers/
• What do we want to know?
– What is the Default Renderer?
– What are the Renderers for other Themes?

How are Renderers Chosen?
Component
Family
Renderer
Type
Renderer
Themes are used to change the components renderer type
Resulting in selecting a different renderer

Finding the Component Family
• Look for getFamily() method in the Component
– Might be in one of the Superclasses
Ctrl + Click

Finding Component Family
• Our Widget Container’s Component Family
– javax.faces.Panel

Component Family
javax.faces.Panel
Renderer
Type
Renderer
Themes are used to change the components renderer type
Resulting in selecting a different renderer

Finding the Default Renderer Type
• Usually is set in the Constructor using setRendererType
Ctrl + Click

Finding the Default Renderer Type
• Widget Container Default Renderer Type is
– com.ibm.extlib.containers.WidgetContainer

Component Family
javax.faces.Panel
Renderer Type
com.ibm.xsp.extlib.containers.WidgetContainer
Renderer

Find the Default Renderer
• “RendererType” is our clue
• Renderer will be registered in a faces config *.xml file
• Let’s Search –> File for the renderer type within *.xml

1 Result that’s easy
• Double click the result

Registration of Renderer in faces-
config.xml

Found our Renderer!

Family + Renderer Type
• If you still couldn’t Determine them from the source

Which Renderers for other themes?
• Theme will change the ‘rendererType’ via properties
using Control ID
• What is the ‘Control ID’ for theming ?
– Lets look for getStyleKitFamily() in the Component;
Ctrl + Click

WidgetContainer Control ThemeId
• Turns out most of these themeId’s are in this
StyleKitExtLibDefault class

Finding Themes that Modify WidgetContainer Properties
• Should be in *.theme files
• Will reference our ‘Container.Widget’ theme id

Found theme
• Lets just look at the
bootstrap one
Double Click the search result

Bootstrap WidgetContainer Renderer
Search for the
Renderer type
In faces-config xml files

Found 1 Result
Double Click

Found Renderer Faces Config
• Use the ‘renderer-class’ to find the actual Renderer

Found our Bootstrap Renderer

About Renderers
• Basic Concept is to Output HTML
Markup
• ‘Encode’ means generate output
– encodeBegin() output before children
– encodeChildren() output the child controls
– encodeEnd() generate output after children
• ‘Decode’ means interpret the response
– User may have input a value that needs to
be given back to the component

ResponseWriter Concept
<div id=“someclientid”>
</div>

How did we go?
• Runtime
– Component Behaviour - FOUND
– Renderers
• Default Renderer - FOUND
– Bootstrap - FOUND
– One UI 2– Could find using same method
– One UI 3 – Could find using same method

SOME EXAMPLES

InPlaceForm Action
• Looked at the DynamicContent action
• Copied elements and modified to suit InPlaceForm
• Shared back to the ExtensionLibrary!

Markdown Control
• Borrowed some logic from Martin Rolph’s (OvalUK) Markdown Custom Control
– With permission!
Edit mode
Read only

Extended InputRichText Control
HTML only (no images)
• Removes CKEditor plugins that allow image uploads
• Prevents Pasting of images (custom CKEditor plugin)

JqGrid Control
• Inspired by Sumit Tayal’s AUSLUG 2015 presentation
– Unmask the True Potential of xGrid
– http://www.slideshare.net/sumittayal78/xgrid-true-potential
• Dynamically generated columns from Notes View Definition
– Learnt and Copied technique from the Dynamic View Control
• Automatically Creates a ‘REST Service’
– Learnt and Copied technique from Extlib Rest service controls;
• Visualizers, Panels
– Looked at other Ext Lib controls for examples
• Automatically add Jquery resources
– Techniques discovered through extlib and also Xpages Community

JqGrid Control

XPages Slack Channel
Sign Up!
• http://xpages-slack-invites.herokuapp.com/

Thanks for your time!
http://auslug.org/survey2016

Links
• Xpages Configuration File Format
– https://www-10.lotus.com/ldd/ddwiki.nsf/dx/XPages_configuration_file_format

Setting Up to Browse Extlib
• Download Things
– Download Eclipse
– Download XPages SDK
– Download Extension Library
• Launch Eclipse
• Install XPages SDK
• Import Extension Library projects
• Configure Xpages SDK

Download Eclipse
Eclipse is an IDE “Integrated Development Environment”
which is usually used for Xpages plugin development

Extract Downloaded Zip
I usually put it in a “c:eclipse-versioneclipse” folder so that I can keep separate
versions available
e.g.
C:eclipse-keplereclipse
C:eclipse-lunaeclipse
C:eclipse-marseclipse

Download Xpages SDK
• Search for it on OpenNTF

Download the Xpages SDK

Start Up Eclipse
Decide where to put your ‘workspace’ (basically a folder for settings and new projects)
I keep separate workspaces for separate versions and so usually name it
V:eclipse-versionworkspace-shortdesc
e.g.
v:eclipse-marsworkspace-extlib

Install the Xpages SDK

Install Xpages SDK

Might see this for a while
Then this
Then this

Download Extension Library

Download this link, and then Extract the Zip to anywhere you prefer

Unzip Source Folders
Unzip the src archives

Import into Eclipse

Choose Existing Projects into Workspace

Importing srcOpenNTF

Add Main Plugins to a Working Set

Importing srcOpenNTF-designer

Show Working Sets

ERRORS!
• Don’t Panic!
• You can still browse the code
Just fine

Disable Maven Nature

Configure Xpages SDK Preferences

Choose Notes JRE

Create a Target Platform

Choose Target Platform

Clean

Delete pom.xml files from all projects

No more errors!
Don’t worry about warnings, there is always warnings

Anatomy of a UI Control - Extension Library Case Study

More Related Content

Similar to Anatomy of a UI Control - Extension Library Case Study

Recently uploaded

Anatomy of a UI Control - Extension Library Case Study