Updated UI addon README

ui/README.asciidoc

@@ -1,23 +1,192 @@
-UI Addon for JBoss Forge 2.0 / Furnace 
-======================================
-George Gastaldi <ggastald@redhat.com>
-:idprefix: id_
+== UI (User Interface)
+:idprefix: id_ 
 
-Addon description 
-
-== Setup 
+This addon enables the creation of user interfaces making them agnostic to the underlying UI provider.
 
-=== Installation 
+In practice, that means that your code will run in any UI provider without requiring any changes.
+
+The UI addon is directly used by UI providers (Eclipse, IDEA, Netbeans, Shell) to render Wizards and single dialog boxes.
+The Eclipse UI provider follows the http://www.eclipse.org/articles/Article-UI-Guidelines/Contents.html#Wizards[Eclipse User Interface Guidelines] 
 
-    forge --install ui 
+NOTE: Implementations of UICommand are displayed in the Forge Quick Assist menu in Eclipse (When Ctrl+5 is pressed)
 
-=== As a dependency of another addon: 
+=== UI Components
 
-Add this to your *pom.xml*: 
+There are basically four input types: 
+
+- *UIInput* : Prompts for a single value. (Eg: Textbox).
+- *UIInputMany* : Prompts for multiple values.  
+- *UISelectOne* : Should be used when the number of items to be chosen are known before rendering the component. Allows selection of only one value (Eg: Combo box)
+- *UISelectMany* : Should be used when the number of items to be chosen are known before rendering the component. Allows selection of multiple values (Eg: Checkbox table)
+
+=== Depends on
+
+[options="header"]
+|===
+|Addon |Exported |Optional
+
+|container-cdi
+|No
+|No
+
+|convert
+|Yes
+|No
+
+
+|facets
+|Yes
+|Yes
+
+
+|ui-spi
+|Yes
+|Yes
+
+|===
+
+== Features
+
+Implementing a simple dialog box:: When interaction does not present a complex workflow and has little arguments
+
+Create a class that extends the *_org.jboss.forge.addon.ui.AbstractUICommand_* and implement the required methods. 
+For each input, inject it in your addon using the CDI @Inject annotation and add it to the UIBuilder:
+
+[source,java]
+----
+public class ExampleAddon extends AbstractUICommand
+{
+
+   @Inject
+   private UIInput<String> name;
+
+   @Override
+   public void initializeUI(UIBuilder builder) throws Exception
+   {
+        builder.add(name);      
+   }
+
+   @Override
+   public Result execute(UIContext context) throws Exception
+   {
+      return Results.success("Hello,"+ name.getValue());
+   }
+
+}
+----
+
+Implementing a multi-step wizard:: When interaction is complex and presents a considerable number of arguments
+
+[source,java]
+----
+public class WizardInitialPage extends AbstractUICommand implements UIWizard
+{
+
+   @Inject
+   private UIInput<String> name;
+
+   @Override
+   public void initializeUI(UIBuilder builder) throws Exception
+   {
+        name.setLabel("First Name").setRequired(true);
+        builder.add(name);      
+   }
+
+   @Override
+   public Result execute(UIContext context) throws Exception
+   {
+      return Results.success();
+   }
+   
+   @Override
+   public NavigationResult next(UIContext context) throws Exception
+   {
+      context.putAttribute("firstName",firstName.getValue());
+      return Results.navigateTo(WizardNextStep.class);
+   }
+}
+----
+
+And create a WizardStep implementation, like the following:
+
+[source,java]
+----
+
+public class WizardNextStep extends AbstractUICommand implements UIWizardStep
+{
+
+   @Inject
+   @WithAttributes(label="Last Name", required=true)
+   private UIInput<String> lastName;
+
+   @Override
+   public void initializeUI(UIBuilder builder) throws Exception
+   {
+        builder.add(name);      
+   }
+
+   @Override
+   public Result execute(UIContext context) throws Exception
+   {
+      String firstName = (String) context.getAttribute("firstName");
+      String fullName = firstName + " " + lastName.getValue(); 
+      return Results.success("Hello,"+ fullName);
+   }
+   
+   @Override
+   public NavigationResult next(UIContext context) throws Exception
+   {
+      //End of interaction, return null
+      return null;
+   }
+}
+----
+
+Creating components dynamically:: If the number of inputs are unknown at compile time, it is possible to create inputs using InputComponentFactory:
+
+[source,java]
+----
+public class ExampleAddon extends AbstractUICommand
+{
+   @Inject
+   private InputComponentFactory factory;
+	
+   private List<UIInput<String>> inputs;
+
+
+   @Override
+   public void initializeUI(UIBuilder builder) throws Exception
+   {
+      UIInput<String> firstName = factory.createUIInput("firstName",String.class);
+      UIInput<String> lastName = factory.createUIInput("firstName",String.class);	
+
+      // Input will be stored in UIInput objects
+      inputs = Arrays.asList(firstName,lastName);
+
+      builder.add(firstName).add(lastName);      
+   }
+
+   @Override
+   public Result execute(UIContext context) throws Exception
+   {
+      String fullName = inputs.get(0).getValue() + " " + inputs.get(1).getValue();
+      return Results.success("Hello,"+ fullName);
+   }
+
+}
+----
+
+
+
+== Setup
+
+=== Service consumer
+
+To consume exported services of this addon, you must add it a dependency in the *pom.xml* of your `forge-addon` classified artifact:
 
       <dependency>
          <groupId>org.jboss.forge.addon</groupId>
          <artifactId>ui</artifactId>
-         <version>${forge.version}</version>
          <classifier>forge-addon</classifier>
+         <version>${version}</version>
       </dependency>