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.

Run the project as an Eclipse Application again and 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.


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.

4 thoughts on “Extending the Force.com IDE

  1. Some awesome stuff here Peter. Thanks! Out of curiosity, what are you opinions in regards to the Force.com IDE now that it has been open sourced? I was a huge Eclipse fan for years (originally coming from Java) and used the Force.com IDE religiously for the first few years of Force.com development. However, after having used MavensMate now for almost a year, I’m not sure I can go back to the clunk and slow Eclipse + Force.com IDE configuration. Do you think many people will start leaving these newer IDEs IMavensMate, BrainEngine, Aside.io, etc) and returning to the IDE? Is it possible that tweaks will occur on the plugin that will dramatically increase performance? I am curious to see where all of this lands in another year or so.

    Anyway, thanks again for the great article. It was a good read and something I personally have never done so it was cool to see the ins-and-outs of the process.

    1. Thanks Jesse. 🙂 I hadn’t done any Eclipse plug-in development before this either. It’s not that difficult and pretty well documented, so wasn’t too difficult to figure out.

      I think that, in general, change is hard and there has to be a justifiable reason to make the change. If you are in a development shop that uses MavensMate and doesn’t have any problems, I suspect you wouldn’t change to use the Force.com IDE, just because it was open-sourced. My thought is that you would change if there were features that it had that were too good to pass up, that MavensMate didn’t. Now that the IDE has been open-sourced, I see that as a real possibility in the future.

  2. Peter, is this step “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” necessary? For previous versions of Eclipse (since when the Plug-in Spy was available, I think 3.6), I have always been able to just use Shift + Opt + F1/F2 without adding the dependency. Has this changed for Luna?

Leave a Reply

Your email address will not be published. Required fields are marked *