AD102 Hacking IBM Lotus Domino Designer (Gently)

Maureen Leland | Gentle Hacker | IBM

2

Agenda● What is IBM Lotus Domino Designer® made of?

▬ Make the most of the Eclipse within

● Add your own menu items

● Don't like our editor? Ours is missing? Write your own!

● Contribute your own perspective

● Q & A

3

Is it Designer, or is it Eclipse?● Yes :-)

▬ Domino Designer 8.5.x is based on Eclipse 3.4.2

Domino Designer 8.5.x

Eclipse 3.4.2

NotesClient 8.5.x

Expeditor 6.2.x

WTP

4

Designer Philosophy● Blend the rapid development that has always been Domino Designer

with the flexibility and extensibility of Eclipse● No barriers – for users unfamiliar with Eclipse as well as for

experienced Eclipse users▬ Other perspectives should function as “pure” Eclipse▬ Designer perspective(s) streamlined for Domino development

● If Eclipse has an implementation, Designer leverages it rather than reinvents it

▬ e.g.: working sets▬ Virtual file system representation of databases (more on that later!)

5

Unleashing the Eclipse Within● Eclipse itself has a myriad of settings and controls● Most preferences exposed by Eclipse are available in Designer

▬ Challenge is often finding them in preferences● Let's look at Eclipse's solutions to a few common Designer requests!

Too Many Search Results?● You can control the scope of your selection

Too Many Problems?● Configure your problems view!!!

I Like My Font Bigger... Smaller... Green....● Font control for specific editors

Useful Plugins Others Have Written● Subclipse: integrates Eclipse with Subversion (SVN)

▬ http://subclipse.tigris.org/● MercurialEclipse: alternate source code management

▬ http://www.javaforge.com/project/HGE● Source Control Enablement for Designer

▬ Connects Designer to ANY source control management plugins you have installed (SVN, Mercurial, CVS...)

▬ http://www.openntf.org/internal/home.nsf/project.xsp?action=openDocument&name=Source%20Control%20Enablement%20for%20Designer

● XPages Extension Library▬ http://extlib.openntf.org/

10

Working with the Virtual File System● Virtual file system support part of Eclipse since Eclipse 3.3

▬ NSF implementation provided by the Designer code ▬ Not visible outside Designer

● Every database opened in Designer is considered an Eclipse IProject● Design element categories each map to an IFolder● Each design element is an IResource● Each design element ends in a distinct extension...

▬ MyForm.form▬ AllDocuments.xsp▬ MyView.view▬ Etc.

● Create, read, write, delete, etc. design elements through the Eclipse IResource API

11

Agenda● What is Domino Designer made of?

▬ Make the most of the Eclipse within

● Add your own menu items

● Don't like our editor? Ours is missing? Write your own!

● Contribute your own perspective

● Q & A

12

Building Plugins for Designer● First need a development environment for building Designer plugins....● Eclipse 3.4.2

▬ Get Eclipse from: http://www.eclipse.org/downloads/packages/release/ganymede/sr2

● Then add in the Expeditor toolkit▬ Get the toolkit from:

http://www14.software.ibm.com/webapp/download/nochargesearch.jsp?q=Lotus+Expeditor+Toolkit+6.2

● Add the toolkit in to Eclipse as an Update Site● It will automatically relaunch....

13

Contributing to Designer's Menus● All Designer menus are extensible Eclipse

menus▬ Popups (right-click) and main menus ▬ Typically separators are “add-in” points▬ You place your contribution by “path” to the add-in

point● Eclipse provides several ways to implement

menus....▬ Actionset, command, handler, menu...▬ Each is an extension for which you can provide an

implementation● Let's add “Save All” to the File menu

▬ Individual menu item, so want an action not a menu▬ One-off addition, so no need to factor code off in to a

command▬ But we could if we wanted to...

▬ We'll place it at “file/additions”● Let's go do it!

file/additions

14

Recap of Menu Hacking● Eclipse has templates, but more complicated than we need● So start with empty plugin● Go to extensions, add org.eclipse.ui.actionset● Add an action to the action set...● Create a class that implements IWorkbenchWindowActionDelegate● Leverage the Eclipse builtin ActionFactory.SAVE_ALL action● Try it out● Create an Update Site from our new plugin● Share the update site with anyone missing Save All :-)● See the “after-slides” for step by step screenshots

15

Agenda● What is Domino Designer made of?

▬ Make the most of the Eclipse within

● Add your own menu items

● Don't like our editor? Ours is missing? Write your own!

● Contribute your own perspective

● Q & A

● The VFS makes DXL easy● Load the IResource into any DOM / SAX parser● EMF (Eclipse Modeling Framework) can generate your API

▬ Also includes option to generate a default editor and test cases▬ Just feed it the DXL schema and it generates the code for you

● Set your preferences to edit .form / .view files with your custom editor● Saving the file immediately updates the design element

Creating a Custom Design Element Editor

Managing Your Managed Beans● By default, managed beans are defined by hand-editing XML● As this is not a daily task, the format is easy to forget● This is a perfect example of a “pet peeve” feature...● ...but this is a very easy editor to create

▬ faces-config.xml is stored in WebContent/WEB-INF▬ We can create an Eclipse editor to edit this specific kind of file▬ Every managed bean definition maps to a mere 5 lines of XML

Plotting our Custom Editor● We're going to create a plugin● The plugin will extend the editor extension point● The editor will:

▬ parse the xml in the faces-config.xml▬ gather the information for the new Bean▬ Add the new definitions into the XML Document using DOM manipulation classes▬ Save the IFile back to the file system

▬ Happens to be a virtual file system, but Eclipse doesn't care!!

Recap of Custom Editor Creation● Implement the required methods for the EditorPart● Parse, then manipulate, the XML programmatically● Use SWT Text and Label controls to gather the new values

▬ Exercise for the reader... Use a combobox for the Scope with the valid values!● Overwrite the existing IFile with the modified XML● Because we've associated the editor with this filename, we don't need a

menu item!● See the “after-slides” for step by step screenshots

20

Agenda● What is Domino Designer made of?

▬ Make the most of the Eclipse within

● Add your own menu items

● Don't like our editor? Ours is missing? Write your own!

● Contribute your own perspective

● Q & A

21

Putting Perspectives in Perspective● Designer 8.5.2 provides a single perspective● Manages layout of the UI as well as menu contributions● Two options

▬ “start from scratch”▬ Full control, full responsibility

▬ Contribute to the Designer perspective▬ Let Designer handle most of the work, add in just what you need

● Scenario: Corporate branding and styles, want help information at the ready

▬ Let's try the easy way!

22

Plotting our Perspective Hack● Like a normal Eclipse IDE, Designer has a single “edit part” surrounded

by a variety of “view parts”● Contributions to a perspective are thus usually view parts, one for each

component

Edit part

View parts

View parts

Our new views

23

Recap of Perspective Hacking● Create the view parts using Eclipse wizards

▬ Just need a simple browser control in each● View parts are positioned in the perspective through perspective

extensions▬ Choose the Designer perspective to extend▬ Add a view extension for each view part to add▬ Position it within the perspective relative to another piece of it

● When developing your add-in, “Reset Perspective” is required, to force Eclipse to show your changes (unless you want a new workspace each time...)

● See the “after slides” for step by step screenshots

24

Summary● Domino Designer is most definitively hackable● Domino Designer is most enjoyably hackable● Roll up your sleeves, and join the team!● Share what you can on OpenNTF so our entire community can benefit

25

Questions????

26

Appendix

● The following slides are provided to help you try the demos yourself● Have fun!!

27

Setting up Your Environment● When the workspace opens....● Test enviroment is Lotus Notes 8

▬ Yes, that works for Designer, too :-)▬ Sets up “target platform” to be the Notes/Designer version of Eclipse

28

To Test Run the Plugins You'll Write...● Need to set up a debug/run configuration● Create a New Client Services configuration, with choices like below

29

Step by Step for Menu Hacking● Begin by creating a plugin project...

30

Menu Hacking (2)● Create it empty (just press Finish), as it's easy enough that we don't

need to use any of the (myriad) templates available● When it wants to switch perspectives, go ahead!

31

Menu Hacking (3)● Edit MANIFEST.MF, go to the Extensions tab, press Add, and choose

the org.eclipse.ui.actionSets extension

32

Menu Hacking (4)● Set visible to “true” (VERY IMPORTANT!!)● You can change the label to be something more meaningful

33

Menu Hacking (5)● Next, right click on the actionSet in the left pane, and choose

New/Action, and fill out the right hand side of the editor below, as shown

34

Menu Hacking (6)● A minor follow-ups

▬ MANIFEST.MF will be showing an error, allow the source editor to correct it to▬ Bundle-SymbolicName: MyMenuPlugin;singleton:=true

● Then need to write the code for the class we just told the editor about!!▬ File.. New... Class (with same name given in the Action definition)

ExtendAn Interface

Name it

35

Menu Hacking (7)● Fill in the class

implementation....● Test it out● Build the update

site (see the next section for details!)

36

Building an Update Site● File – New – Project (select Update Site Project)

37

Building an Update Site (2)● Give it a Project name, and press finish

38

Creating an Update Site (3)● Need a feature to wrap your plugin, so create a New Feature Project

39

Creating an Update Site (4)● Select your plugin

40

Creating an Update Site (5)● When the new feature project opens, you'll be editing the feature.xml,

where you can provide a description and set any parameters you may need

41

Creating an Update Site (6)● Add the feature to the update site you created....

Select your feature

42

Creating an Update Site (7)● Build the Update Site, and your update site is now ready in your

workspace

Creating a Custom Editor● Create a Plugin project

Creating a Custom Editor (2)● Add an extension, and extend org.eclipse.ui.editors

Creating a Custom Editor (3)● Name the editor (ManagedBeanAdder, for example)● Associate it with the specific filename faces-config.xml● Make it the default● Now we need a class and contributorClass!

Creating a Custom Editor (4)● Add the required plugins to the project dependencies

▬ Some standard Eclipse editor and UI plugins▬ org.eclipse.ui▬ org.eclipse.core.runtime▬ org.eclipse.core.resources▬ org.eclipse.ui.editors▬ org.eclipse.ui.ide

▬ For DOM parsing, you can use your favorite XML utility OR I'm usingthe one Designer uses (just cuz)

▬ com.ibm.commons▬ com.ibm.commons.xml

Creating a Custom Editor (5)● First, create the contributor class (because it's easy)● Extend the EditorActionBarContributorClass

Creating a Custom Editor (6)● First, create the contributor class (because it's easy)● Extend the EditorActionBarContributorClass● All we need is the constructor and for it to exist

Creating a Custom Editor (7)● Last, create the editor part

extension● It's not hard, just some

methods to implement● Extend EditorPart

Creating a Custom Editor (8)● We get some code out of the gate...● Need to override:

▬ setFocus()▬ To put the focus somewhere for when the user starts typing

▬ isDirty▬ Tell Eclipse whether or not the contents have been modified

▬ isSaveAsAllowed▬ In this case false, there's only ONE faces-config.xml

▬ init▬ Get the file contents so we know what we're editing

▬ createPartControl▬ Create the UI controls to gather the bean information

▬ doSaveAs▬ Does nothing, since we don't support this!

▬ doSave▬ To perform the actual save of the file

51

Hacking the Perspective● Create the view parts● Just like creating a menu plugin, but let's use a template this time....

52

Hacking the Perspective (2)● Update the ViewPart code to

do what we want▬ Delete most of it!▬ Replace contents (created in

createPartControl) with a simple SWT Browser control

● Build two view parts, in the same or different plugins (your choice), difference is just the URL

▬ One to the Designer wiki▬ Second to the corporate

standards wherever they may live

53

Hacking the Perspective (3)● Edit plugin.xml● Add a perspective extension

54

Hacking the Perspective (4)● Add the target perspective ID, Designer perspective is right in the list!● Then right click on the extension and choose New... View

55

Hacking the Perspective (5)● Fill in the view parameters in the perspective extension● Match the id for the view part to the id in the definition below● Place the view part in the same place as the Problem view, “stack” it

next to it

56

Hacking the Perspective (6)● Launch Designer from your development environment...● At first, disappointment – it's not there!!!!● Eclipse caches perspective layouts... Reset perspective, and you'll see

your new toy

57

Legal Disclaimer© IBM Corporation 2011. All Rights Reserved.

The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM’s current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software.

References in this presentation to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth or other results.

All customer examples described are presented as illustrations of how those customers have used IBM products and the results they may have achieved. Actual environmental costs and performance characteristics may vary by customer.

IBM, the IBM logo, Lotus, Lotus Notes, Notes, Domino, Quickr, Sametime, WebSphere, UC2, PartnerWorld and Lotusphere are trademarks of International Business Machines Corporation in the United States, other countries, or both. Unyte is a trademark of WebDialogs, Inc., in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

All references to Renovations refer to a fictitious company and are used for illustration purposes only.