= Errai Forge 2 Addon: Shell Guide

== Overview

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

== Getting Started

=== Installing Forge 2.5.0.Final

===== 1. Download link:$$https://repository.jboss.org/nexus/service/local/artifact/maven/redirect?r=releases&g=org.jboss.forge&a=forge-distribution&v=2.5.0.Final&e=zip&c=offline$$[Forge 2.5.0.Final]

.. Download the zip file for Forge 2.5.0.Final in the link above.

.. Unzip the file in your home directory.

===== 2. Add Forge to the PATH Environment Variable

.. In Linux this can be one by opening `$HOME/.bashrc` in a text editor and adding this line:
+
[code]
----
PATH=$PATH:$HOME/forge-distribution-2.5.0.Final/bin
----

===== 3. Install the Core Addons

.. Run this command:
+
[code]
----
forge --install core
----

===== 4. Installing the Errai Forge Addon

.. Run this command:
+
[code]
----
forge --install org.jboss.errai.forge:errai-forge-addon,$VERSION
----
+
where `$VERSION` should be replaced with a version of the Errai Forge Addon.
+
[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.
====

=== Making an Errai Project

===== 5. Create a New Project with Forge

.. Start Forge by running this in the terminal:
+
[code]
----
forge
----
+
You should see a prompt that looks like this (where home is the directory you started Forge in):
+
[code]
----
[home]$
----

.. Run the new-project command:
+
[code]
----
[home]$ project-new --named errai-forge-demo --topLevelPackage org.jboss.errai.demo --version 1.0.0-SNAPSHOT --finalName "Errai Forge Demo" --type war --buildSystem Maven
----
+
In the above parameters:

* *named* is the _artifactId_.
* *topLevelPackage* is the _groupId_.
* *version* defaults to _1.0.0-SNAPSHOT_.
* *finalName* is the name of your project for humans.
* *type* is the packaging type of your project.
* *buildSystem* is the build system used by your project.

.. Forge should now prompt you from within your new project:
+
[code]
----
[errai-forge-demo]$
----

===== 6. Run the Errai Setup Command

.. The `errai-setup` command installs the core dependencies and configurations required for all Errai features (including those required for running Development Mode).

.. In the Forge terminal run this command:
+
[code]
----
[errai-forge-demo]$ errai-setup --versionSelect 3.0-SNAPSHOT --logicalModuleName org.jboss.errai.demo.App --moduleName app
----
+
In the above parameters:

* *versionSelect* is the version of Errai to use.
* *logicalModuleName* is the logical name of the link:$$http://www.gwtproject.org/doc/latest/DevGuideOrganizingProjects.html#DevGuideModuleXml$$[GWT module] for your project.
* *moduleName* is a short name used for referencing your GWT module in urls.

+
[TIP]
.Using an Existing Module
====
If you are running `errai-setup` on a pre-existing project with a GWT module you can replace the `--logicalModule` option with `--moduleSelect` followed by the logical name of your GWT module.
====

===== 7. Add Errai Features

.. The `errai-add-features` command add dependencies and configurations for any selected modules in Errai.

.. To see a list of Errai features, type `errai-add-features --featureSelect` and then press _TAB_ for auto-completion. Here are some brief descriptions of the features (for more information find the documentation on the link:$$http://erraiframework.org/$$[Errai website]):

* *errai-messaging* provides a bi-directional message bus and remote procedure calls.
* *errai-ioc* provides a client-side dependency injection container.
* *errai-cdi-integration* provides a client-side CDI container, network transmittable CDI events, and integration with Errai and server-side CDI containers.
* *errai-ui* provides html5 templating and i18n support.
* *errai-data-binding* synchronizes state between errai-ui templates and model objects.
* *errai-navigation* provides "page" navigation within a single-page app, with compile-time verified internal links.
* *errai-jpa-client* implements a subset of the JPA specification in the browser (on top of local storage).
* *errai-jpa-datasync* synchronizes state between server- and client-side JPA entities.
* *errai-jaxrs* provides a declarative client-side API for accessing JAX-RS endpoints.
* *errai-security* provides a declarative API for securing errai-navigation pages, errai-ui elements, and errai-messaging RPC services.
* *errai-cordova* provides an API for mobile device components and configures a plugin for compiling Errai/GWT applications natively.

.. Install any features you would like to the project by providing them as arguments to `errai-add-features`. For example, here is how you could install `errai-cdi-integration` and `errai-ui`:
+
[code]
----
[errai-forge-demo]$ errai-add-features --featureSelect errai-cdi-integration errai-ui
----

[TIP]
.Removing Errai Features
====
The `errai-remove-features` command works similarly to `errai-add-features` except that you will only be able to remove features that:

* You have previously installed.
* That are not depended on by any other Errai features.
====

==== Generating Test Classes

The Errai Forge Addon can generate GWT Mockito tests for unit testing and GWTTestCase tests for integration testing.

For unit tests run the following:

[code]
----
[errai-forge-demo]$ errai-add-unit-test --testableClassName org.jboss.errai.MyClass --testClassName org.jboss.errai.unittest.MyIntegrationTest
----

* `testableClassName` is the fully-qualified name of the Java class being tested.

* `testClassName` is the fully-qualified name of the test class being generated.

[NOTE]
.Unit Test Package
====
GWT Mockito uses a special classloader that is not compatible with the test setup for integration tests. To work around this, the unit test command generates a custom test-runner that whitelists certain packages *including the package of your unit test*.

It is important that your GWT Mockito tests and GWTTestCase tests be in *different* packages.
====

For integration tests run the following:

[code]
----
[errai-forge-demo]$ errai-add-integration-test --testClassSimpleName MyIntegrationTest --testPackageName org.jboss.errai.integrationtest
----

* `testClassSimpleName` is the simple name of the test class being generated.

* `testPackageName` is the root package for the test GWT module.

[NOTE]
.Requires Errai CDI
====
Integration tests require Errai CDI. You will not be able to run this command until you add Errai CDI you your project with the `errai-add-features` command.
====

=== Running Your Project

You've now setup everything you need to start developing a project with Errai. To verify that everything has worked correctly, you can exit Forge and run the following command from within your new project's main directory:
[code]
----
mvn clean gwt:run
----

This may take a while to run the first time, but it should eventually open a GWT Development window. If you press _Launch in Default Browser_, you should eventually see a very exciting blank page in your web browser.

To learn more about what to do next, check out the documentation and other resources on the link:$$http://erraiframework.org/$$[Errai website]!

== 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].
