Anatomy of a UI Control - Extension Library Case Study

Anatomy of an XPages UI Control

Cameron Gregor | Systems Developer Jord Internationalwww.jord.com.au

Blog: camerongregor.comTwitter: @gregorbyte

http://www.jord.com.au/

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’ informationFor 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


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 DetailsNo mention of Icon though?

VisualizationBUT 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 UIWidgetContainerUIDialog

• 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 placeall the properties back inthere fields, ready to useduring the execution of theXpage


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 typeResulting 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 typeResulting 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 typeIn 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

http://www.slideshare.net/sumittayal78/xgrid-true-potential


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-version\eclipse” folder so that I can keep separate versions available e.g.C:\eclipse-kepler\eclipseC:\eclipse-luna\eclipseC:\eclipse-mars\eclipse


Download Xpages SDK

• Search for it on OpenNTF


Download the Xpages SDK


Start Up EclipseDecide 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-version\workspace-shortdesce.g.v:\eclipse-mars\workspace-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

Software

Transcript of Anatomy of a UI Control - Extension Library Case Study