View source for RDP ToPrefixArea

This page is intended to share the steps necessary to create a simple RDi 9.0 plug-in.  This plug-in is a User Action - it can be assigned to a key combination and used within the editor to jump the cursor between the text area and the prefix area.

== Switch to the Plug-in Development perspective ==
* Window > Open Perspective > Other... Plug-in Development
* Make sure you have the Package Explorer view available

== Create a new plug-in project ==
* File > New > Plug-in Project
* Fill in the name of the project.  This will become the name of the generated .jar file.  Case is very important!

[[File:new_plugin_project_1.png]]

* Click Next.
* The next panel describes some of the details of the project.  The defaults look good.  

[[File:new_plugin_project_2.png]]

* Click Next.
* The next panel is asking if you want to use a template.  Don't use a template.

[[File:new_plugin_project_3.png]]

* Click Finish.

== Set the plug-in properties ==

=== Overview ===
* Look at the editor view on the right.  There is a new tab there with your project on it.  Click on the Overview tab.

[[File:overview_1.png]]

* The defaults look OK.  Click on the Dependencies tab.

[[File:dependencies_1.png]]

* Click the Add... button to add a required plug-in.

[[File:dependencies_2.png]]

* Filter on com.ibm.lpex
* Click on com.ibm.lpex
* Click OK.
* Click on the Runtime tab

=== Runtime ===
This is the Runtime tab.  We need to tell Eclipse that our soon to be completed plug-in is available for public use.

[[File:runtime_1.png]]


* Under Exported Packages, click Add...

[[File:runtime_2.png]]

* Select the class we're working on (here, com.kc2hiz.lpexextensions) and click OK.
* Press Ctrl-S to save 
* Click the Extensions tab

=== Extensions ===
Here we tell Eclipse about any extensions this plug-in will need.  We're extending lpex.preload (for the Activator).

[[File:Extensions_1.png]]

* Click Add...

[[File:Extensions_2.png]]

* Filter on com.ibm.lpex
* Select com.ibm.lpex.preload
* Click Finish

[[File:Extensions_3.png]]

* The wizard generated a name for the extension that we don't want.  
* Click Browse...

[[File:Extensions_4.png]]

* On the Browse window, select Activator - com.kc2hiz.lpexextensions
* Click OK
* Ctrl-S to save

== Add a class file ==
Now that the shell of the plug-in is prepared, it's time to drop in the code that will actually do the work we're after.

[[File:class_1.png]]

* Look at the Package Explorer view
* Find your new plug-in (Here, com.kc2hiz.lpexextensions)
* Find the src folder
* Inside the src folder, find the package com.kc2hiz.lpexextensions
* Right click that
* Select New > Class...

[[File:class_2.png]]

* Name the action.  Here, it's ToPrefixAreaAction
* This Action is extending an existing Interface, so we need to tell Eclipse what Interface that is.  Click Add... under Interfaces.

[[File:class_3.png]]

* Filter on Lpex
* Choose LpexAction - com.ibm.lpex.core
* Click OK

[[File:class_4.png]]


When you click Finish, the wizard will generate a new Java source file based on the settings made here.

=== Edit the class that does the work ===
Finally, we're at the part where we're writing some code.  Basically, everything we need to do for this action can be handled in the doAction() method, but we're also going to put code in the avaioable() method to report back when we can use this plug-in.

* Java editor opens with generated source

[[File:ToPrefixArea_1.png]]

* As generated by the wizard

[[File:ToPrefixArea_2.png]]

* Edit available()
** Change arg0 to view
** If the current element (editing window) is present AND is writable, return 'true'

[[File:ToPrefixArea_3.png]]

* Add doAction() code
** Change arg0 to view
** Add code that tests if we're already in the prefix area or not.  If so, move to the text area.  If not, move to the prefix area.
* Ctrl-S to save

=== Edit Activator.java ===
This class tells Eclipse what work to do when the plug-in is started or stopped.

[[File:Activator_1.png]]

As generated by the wizard.

[[File:Activator_2.png]]

* Edit Activator
** Extends com.ibm.lpex.alef.LpexPreload
** Add empty public void preload() method
* Ctrl-S to save and compile

== Export the plug-in ==
At this point, all of the code is written.  Yes, those two little Java files make up the plug-in.  Well, them and the MANIFEST.MF and plugin.xml.  And build.properties helps with the process of keeping all the pieces aligned in the IDE.  The export process packages up all the necessary .class files and other anciliaries into a single .jar file which then can be deployed into any RDi configuration and used after a restart.

=== Export wizard ===
* Click on the Overview tab

[[File:export_1.png]]

* Click on the Organize Manifests Wizard link

[[File:export_2.png]]

* Click Finish
* Click on the Export Wizard link

[[File:export_3.png]]

* It's important to export as a directory.  Record the export location; you'll need it to deploy the plug-in.
* Click Finish
* Close RDi


=== Copy jar file ===
* Open Windows Explorer 
** Position to the directory you recorded above.  Here, it's c:\buck\rdi9
** Open the plugins folder
* Open a second Windows Explorer
** Position to the directory where you installed RDi.  Here, it's c:\Program Files\IBM\SDP
** Open the plugins folder

[[File:copy_1.png]]

* Copy the .jar file from the export directory into the SDP\plugins folder.
* RDi 9.6 and up: Copy the .jar file from the export directory to the program files\ibm\dropins folder. You may need to create the dropins folder.

== Set up RDi to use the new plug-in ==
*Start RDi.  If you've been tinkering with this plug-in, you might want to use the -clean parameter.  I keep a separate icon with that option.  We're now going to tell RDi about our new plug-in and assign it to a keystroke.

=== User Actions ===
First, tell RDi that we have a new user action available.

* Windows > Preferences
* LPEX Editor
* User Actions

[[File:user_actions_1.png]]

* Give the action a name.  I find it simplest to name it the same as the Java class.
* Identify the class that implements this action.  Here, it's com.kc2hiz.lpexextensiotn.ToPrefixAreaAction
* Click Set
* Click Apply

=== User Key Actions ===
Finally, assign the user action to a keystroke.  I chose Ctrl + ` (the back-tick, below Escape and above Tab).

* Windows > Preferences
* LPEX Editor
* User Key Actions

[[File:user_key_actions_1.png]]

* Give the action a name.  I find it simplest to name it the same as the Java class.
* Identify the class that implements this action.  Here, it's com.kc2hiz.lpexextensiotn.ToPrefixAreaAction
* Click Set
* Click Apply


[[File:user_key_actions_2.png]]

* Give the action a name.  I find it simplest to name it the same as the Java class.
* Assign a key.  Here, it's c-backQuote.p.  The trailing .p tells Eclipse that we want to enable this keystroke in the prefix area
* Fill in the name of the action assigned above.  Here, it's ToPrefixArea
* Click Set
* Click Apply
* Assign the same key, but this time with a trailing .t which tells Eclipse we want to enable this keystroke within the text area
* Fill in the name of the action assigned above.  Here, it's ToPrefixArea
* Click Set
* Click Apply
* Click OK

Now test the new action by pressing Ctrl-` multiple times inside an IBM i source member.  The cursor should move between the prefix area (line numbers) and the text area( the editable source).

== Notes ==
If using the 'drop in' method of installing a plug-in, an Eclispe / RDi upgrade might de-register the plug-in. Here's what [https://www.eclipse.org/eclipse/development/readme_eclipse_4.6.php Eclipse 4.6 README] has to say:

Dropped in bundles may not resolve after upgrade

If you have installed bundles by dropping them into the plugins or dropins directory, they might no longer resolve when you upgrade to a new Eclipse Platform version. In each new version of the Eclipse Platform, there are new versions of bundles included in the platform, and often a small number of removed bundles. This may cause your previously dropped in bundles to no longer resolve and run. It is always recommended that you install software via the Help > Install New Software mechanism so you are made aware of any install-time failure to resolve dependencies. 

== Categories ==
[[Category:WDSC]]
[[Category:Editors]]