Anatomy of a UI Control - Extension Library Case Study

transcript

Anatomy of an XPages UI Control

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

Blog: camerongregor.comTwitter: @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’ 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>

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

• 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

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

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