How to create an add-in project in Eclipse

Summary The following document will guide you through the step-by-step process of creating a new add-in project using the Eclipse integrated development environment (IDE). This workflow can be followed for any one of the ArcGIS Desktop software applications that support the Add-In Framework.

In this topic

About creating an add-in in Eclipse

Creating an add-in project in Eclipse
Setting properties

Creating different types of customizations

About creating an add-in in Eclipse

The following document will guide you through the process of creating a new add-in project using the Eclipse IDE. Before beginning this workflow, you must make sure that you have a supported version of the Eclipse IDE installed along with the ESRI provided plug-in. These instructions define an add-in project for ArcMap since there is no difference creating an add-in project for any one of the supported ArcGIS Desktop software products. The same workflow can be applied to create an add-in project for the other supported desktop products. Also, it’s important to note that creating an add-in project is different than defining a particular type of add-in (for example: button, tool, and so on). This document examines the process of creating an add-in project using Eclipse. Creating different types of customizations will point you to documentation describing each type of add-in.

The workflow for creating an add-in project in Eclipse consists of the following two steps:

Creating an add-in project in Eclipse
Setting properties

Step 1 will examine the process for creating a new ArcMap add-in project in Eclipse. Step 2 will examine all of the properties that can be set for the add-in project with detailed descriptions of each property.

Creating an add-in project in Eclipse

This step of the workflow assumes that you have opened Eclipse and have setup a workspace location that you would like your project to be stored in on disk. With that in mind, follow these steps to create a new Eclipse add-in project:

From the File menu, choose New and select Project.

In the New Project wizard, do the following:

Expand ESRI templates, then the ArcGIS extensions folder, and then desktop.

Select ArcMap add-in project.

Select next.
For project name, enter any name for your add-in project.
Click finish to create the project.

Clicking next instead of finish gives you more Java setting options (for example: additional libraries you might need to reference). However, if you are only working with add-ins and do not require any additional Java properties, like referencing an external Jar, then clicking finish will already do the job of referencing the arcobjects.jar library needed to construct your add-ins. If unsure if the settings are necessary, you can click next and examine the additional settings for your project.

When finished, a new Eclipse add-in project is created for you with the project name you supplied in the new project wizard. The project will automatically generate the necessary library references and the config.xml file for you. The config.xml is opened using the Add-In Editor. Notice that the Add-In Editor does not display eXtensible Markup Language (XML), as you might expect, but rather a form based editor. The Add-In Editor actual provides you with two views: one with a form based editor and another with the actual XML source.

Add-In view - A form based editor of your config.xml that allows you to quickly define properties for your add-in project and your add-in types.

Source view - A source view shows the raw XML for the config.xml file.

The add-in and source views illustrated are synchronized with one another. For example, if you make a change to a text box in the add-in view, then that change is automatically reflected in the source view. The preceding image has a value for the name property, and this is reflected in the source view with this value placed between the name XML tags. However, if you removed the name value in the associated property field in the add-in view, then you would see an empty name tag displayed in the source view.

The add-in editor is extremely useful because it will provide you with all the necessary details you require when developing an add-in project and any type of add-in without concerning yourself with the proper XML syntax. To help you minimize the potential for error when defining the config.xml, using the add-in editor is recommended. All the workflows that will be presented to you will use the add-in view of the add-in editor.

Setting properties

After you have finished creating your project, the next step in the workflow is to set properties found under the overview section of the editor. These properties are essentially the project’s meta-data and become important at deployment time when the add-in is being used by yourself or your end users. You can define as many types of customizations as your organization requires in a project and the meta-data acts as a way to describe the different types of add-ins as a group. Ideally, all the customizations that you define for a given project should form some logical grouping. Following this strategy will help keep your functionality organized when it is being utilized by the end user and when you are trying to maintain your projects.

The add-in overview refers to the following section of the editor:
Image of the Add-In Overview section of the Add-In Editor.

The following is a description of each property:

Name* - The name of the project. This should be a descriptive name that encompasses all of the customizations that will be developed for this project (Required).

Version* - The version of the project is used to determine the deployment release number of the add-in. By default a value one 1.0 is used; however, when new versions of your projects are defined, you can update this value to 2.0. It is also possible to increase versions in decimal point increments (for example: 1.1, 1.2, 0.1, and so on). See, How to version your add-in, for the workflow that defines how to version your projects (Required).

Company - The name of your organization (Optional).

Description - A brief description to describe the purpose of your project. This should be a description that encompasses all of the types of add-ins that will be developed for this project (Optional).

Author - The name of the developer who created the project (Optional).

Image - If you would like to incorporate an image for your project you must create an image folder within your Eclipse project. After that, place your image into that folder and use the browse button to navigate to your image (Optional).

The asterisk (*), as seen in the editor, indicates that the property is required. The name and version properties defined are required, but as you continue to work with the editor dialog you will notice the asterisk is used when setting other properties for the types of add-ins that you define, these are also required properties.

The following properties: name, company, description, and image are all used after your add-in project is deployed (see How to deploy your add-in for workflows on this process). The following illustrates an example of how this meta-data is used after your project is deployed. For this example, the following values were entered into the overview section:

After these properties are filled out and the project is deployed, using the Add-In Manager from ArcMap, the following can be observed:
Image of the Add-In Manager for ArcMap.

Notice that the name, version, company, description, and image properties are used by the Add-in Manager. This information can be useful, especially if there are more than one add-in projects to choose from or multiple versions of an add-in.

Creating different types of customizations

The following document showed you steps for creating and setting properties for an add-in project. The next step is to start creating your individual types of add-ins. The following documentation points you to documents that teach you how to create individual customizations.