plugIn

Extending the Force.com IDE

The Force.com IDE is an Eclipse Plug-in, built on the Tooling API, that provides the functionality of an integrated development environment for Force.com projects.  In the beginning of July, Salesforce.com open sourced the plug-in code.

In this article I describe how to get started with extending the plug-in by stepping through an example of adding a toolbar button to launch Workbench (workbench.developerforce.com) in the default browser.  The article explains how to get the code, bring it into Eclipse, make changes, run the plug-in, inspect the plug-in, export it, and install it.

Getting the Code

The code for the plug-in is located in the GitHub repository at https://github.com/forcedotcom/idecore.  The GitHub directions for forking a repo can be followed to fork and clone the repo to your local machine.  When I forked the repo it created https://github.com/peterknolle/idecore for me and I cloned it by giving the command $ git clone https://github.com/peterknolle/idecore on my local machine.

Importing into Eclipse

The plug-in code depends on some features that are not part of the standard Eclipse installation.  The easiest way to ensure you have the necessary dependencies satisfied is to use the Eclipse IDE for Java EE Developers which comes with the Eclipse Web Tools Platform and the Eclipse Plug-in Development Environment.  I downloaded and used the latest version, Luna, for this article. Note that you do not need to install the Force.com IDE plug-in into it since you’ll be running the plug-in directory from the project source code and then later installing your own version.

After installing Eclipse, the first step is to import the projects. The plug-in is imported as 12 Eclipse projects. To import it, you can go to File | Import… and choose Existing Projects into Workspace and find the root of your repository.
Select Projects for ImportFrom that screen, select all of the projects and import them.  Once they are imported they will appear as 12 different projects in the Package Explorer.

Projects in Package Explorer after Import

Running the Plug-in

The plug-in can be run by right clicking on the com.salesforce.ide project and selecting Run As | Eclipse Application.
Run As Eclipse Application

Doing that will open a new Eclipse window, with the plug-in installed.  You can create a new Force.com project as you normally would by navigating to New | Other… | Force.com Project and entering in the correct configuration and credentials.  As you make changes to the plug-in source code and configurations you can test them by launching the application this same way.

Note that you can, alternatively, start it in debug mode by selecting Debug As | Eclipse Application.

Inspecting the Plug-in

The Eclipse Plug-in Development Environment has a feature called Plug-in Spy that allows the developer to get information about different elements of any running plug-in.  This is useful for exploring and reverse engineering existing functionality.  In this case, I wanted to add a toolbar button to launch the default browser to Workbench, which is basically the same as the existing functionality of the buttons that launch to the Developer or Salesforce.com sites.

To be able to use the Plug-in Spy while running as an Eclipse Application you must first add a dependency in the project to org.eclipse.pde.runtime.  Do this by double clicking the plugin.xml in the com.salesforce.ide project to get to the edit view and select the Dependencies tab.  From there, click the Add… button and add the dependency.
Select DependencyAfter the dependency has been added the Dependencies tab will appear as follows.
Dependencies after added

Run the project as an Eclipse Application again.  This time you will be able to use the Plug-in Spy capabilities.  There is a lot more detail on the Plug-in Spy in this article, but it is fairly straightforward.  Simply select something (e.g., a file in the src folder package explorer) and hit Alt+Shift+F1 to get information about it, or click Alt+Shift+F2 to enter into a menu spy mode that will enable you to navigate to or select menu items to get information about.  On the mac, it is Option+Shift+F1 or F2 and I had to change Keyboard preferences to “Use all F1,F2, etc. keys as standard function keys”.

When the menu spy is executed on the “Open Default Browser to Developer Force Button” it reveals the following information that indicates actions and action sets are used.

Plug-in Spy for launch to developer force buttonThere is much more about Action Sets in their help documentation.  It’s worth noting that they are deprecated so they should not be used for completely new areas of functionality.

Adding the Functionality

The rest of the work is to just copy the openToDeveloper configurations and modify them to open to Workbench.  The plugin.xml GUI editor has an Extensions tab which allows you to see the existing extensions and make some limited changes.  My IDE generated errors when I tried to use that GUI.

Open the plugin.xml in the com.salesforce.ide.ui project and find the openToDeveloperAction.  A new action openToWorkbenchAction should be added, so that the actionSet element is as follows (note that the 3rd action element is new).  The new element refers to icons and other attribute values that need to be created first.

In the com.salesforce.ide.ui config/ui-application-context.xml (yes, that’s Spring) create an openBrowserToWorkbenchAction.  Note that the same class, OpenBrowserToExternalSiteAction.java, that is used for opening the other sites is reused.

Add an icon to com.salesforce.ide.ui icons/icon_workbench.png (or wherever it is specified in your action’s icon attribute). Add a property to the com.salesforce.ide.ui plugin.properties file for the tooltip and label, action.label.OpenWorkbench=Open Default Browser to Workbench.

At this point, the new feature should be fully functional and can be seen when running the project as an Eclipse Application.
Plug-in running with new feature

Exporting and Installing

Once the development is complete the projects can be exported to jar files so that they can be used for real in the non development environment.  To export, click on the com.salesforce.ide plugin.xml to bring up the Overview tab. Click the Export Wizard and select all of the projects.
export jars dialogOnce you have the jar files built, you can copy them into the dropins directory of Eclipse (e.g.,  /Application/Eclipse/dropins) and restart Eclipse.  That will install the plug-in.  If you later remove the jar files from the dropins directory it will uninstall the plugin.

Managing the Code

As development is being done, code can be committed locally and then pushed to the remote fork repository as needed.  Much more can be done with branches, pulling in upstream changes, etc.  There’s lots of documentation on that, but the basics are on the how to fork a repo page.  If you do something worthwhile that you want to get added to the master branch, you can create a pull request.  Salesforce.com employees are the only committers on the master branch.  More information on that in the announcement blog post.

More

The Force.com IDE plug-in being open sourced was a great achievement that will lead to community members making relevant improvements.  You can see and track feature requests and defects in the GitHub issue tracker.

There are some very good tutorials written by Lars Vogel on Eclipse plug-in development, such as his Eclipse Plug-in Development Tutorial that are helpful in getting started.  Additionally, the Eclipse help sections / guides on Plug-in Platform Development, the Eclipse Wiki, and the Eclipse Plug-in Development Environment (PDE) site contain a wealth of information on developing plug-ins for Eclipse.