= Errai Forge 2 Addon: Eclipse Guide

== Overview

This guide explains how to install and use the Errai Forge Addon via the Forge Plugin for Eclipse. You can see instructions link:$$SHELL.asciidoc$$[here] if you prefer to use it in the shell.

== Getting Started

=== Installing Eclipse

===== 1. Download and Install the link:$$http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/keplersr1$$[Eclipse IDE]

.. Follow the link above and download the appropriate version of Eclipse for your OS and hardware.

.. Run the Eclipse installer.

===== 2. Install the link:$$http://www.eclipse.org/m2e/download/$$[Eclipse Maven Plugin]

.. If you have downloaded Eclipse following step (1), you already have the plugin and may skip this step.

.. Otherwise, follow the Eclipse Maven Plugin link and drag the _Install_ icon into your running instance of Eclipse.
+
image:images/m2e-install.png[]

=== Installing Forge 2 and the Errai Forge Addon

===== 3. Install the link:$$http://download.jboss.org/jbosstools/builds/staging/jbosstools-forge_master/all/repo/$$[Forge 2 Eclipse Plugin]

.. In the Eclipse menu, go to _Help_ > _Install New Software..._
+
image:images/install-new-software.png[]

.. Paste the link Forge Eclipse Plugin link into the text field and press _Enter_.
+
image:images/add-forge-plugin-url.png[]

.. Select _Jboss Tools Forge Nightly Build Update Site_ and click _Next_.
+
image:images/select-jboss-tools-forge.png[]

.. Review the installation details and then click _Next_.
+
image:images/review-forge-install.png[]

.. Review and accept the licensing information, then click _Finish_.
+
image:images/forge-licensing.png[]

===== 4. Install the Errai Forge Addon

.. In Eclipse, press _Ctrl_ + _4_ to activate the Forge Plugin. It may take a few moments to load when first called.

.. In the Forge text field, type _install_ and select _Install an Addon_.
+
image:images/forge-install-addon.png[]

.. In the prompt, enter the following values for each field and then click _Finish_:

** _Group ID_: org.jboss.errai.forge

** _Name_: errai-forge-addon

** _Version_: 3.0-SNAPSHOT
+
image:images/enter-addon-coordinate.png[]
+
[IMPORTANT]
.Published Versions
====
link:$$http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.jboss.errai.forge%22%20AND%20a%3A%22errai-forge-addon%22$$[Here] you may find the published versions of the Errai Forge Addon. Since Errai version _3.0.0.20140325-M5_, the addon version mirrors that of Errai. To avoid unnecessary difficulties, we advise you to use a version of the Errai Forge addon that matches the version of Errai you are installing.
====

=== Setting up an Errai Project

===== 5. Make a new Project with the Forge Plugin

.. Activate the Forge Plugin again and type _project_, selecting _Project: New_.
+
image:images/forge-new-project.png[]

.. Fill in the fields with your new project's information.

** For _Project Type_ select _Java Web Application_.

** For _Build System_ select _Maven_.
+
image:images/forge-create-new-project.png[]

===== 6. Setup Errai in the New Project

.. In the Eclipse _Package Explorer_, select your new project and then activate the Forge Plugin.
+
image:images/select-project.png[]

.. In the Forge menu, select _Errai: Setup_.
+
image:images/setup-errai.png[]

.. Follow the prompts until the _Add Errai Features_ prompt.
+
image:images/select-version.png[]
+
image:images/select-gwt-module.png[]
+
image:images/enter-module-logical-name.png[]
+
image:images/rename-gwt-module.png[]

.. If you wish, you can select Errai Features to install at this point. Below we will discuss how to add or remove Errai features outside of the setup wizard.
+
image:images/add-features-list.png[]

=== Adding and Removing Errai Features

After the above setup has been performed, it is possible to add or remove Errai features at any time:

1. In Eclipse, activate the Forge Plugin.

2. Select one of the commands _Errai: Add Features_ or _Errai: Remove Features_.
+
image:images/add-or-remove-feature-commands.png[]

3. When prompted, select the features you wish to add or remove.

And that's it! The Errai Forge Addon will make any necessary configurations to your project, as well as installing any additional Errai features required.

=== Errors in POM File

Your version of Eclipse may complain of not having an m2e connector for the gwt-maven-plugin. In this case:

1. Find the error in your POM file.

2. Do a quick fix (_Ctrl_ + _1_).

3. Select _Permanantly mark as ignored..._

=== Running Your new Project

For instructions on how to run your new project, and for setting up Eclipse Run Configurations, please see the Errai link:$$https://github.com/errai/errai/blob/master/errai-docs/src/main/asciidoc/reference.asciidoc#running-the-app-in-gwts-development-mode$$[Getting Started Documentation].

Happy Coding!

== Feedback

If you have any feedback or would like to report a bug, please check out our link:$$https://community.jboss.org/en/errai?view=discussions$$[forum] and our link:$$https://issues.jboss.org/browse/ERRAI$$[Jira].
