Migrate ComponentAddonProjectSetupHowto

1 files changed, 174 insertions, 0 deletions

diff --git a/documentation/articles/ComponentAddonProjectSetupHOWTO.asciidoc b/documentation/articles/ComponentAddonProjectSetupHOWTO.asciidoc
new file mode 100644
index 0000000000..3d633b82fa
--- /dev/null
+++ b/documentation/articles/ComponentAddonProjectSetupHOWTO.asciidoc
@@ -0,0 +1,174 @@
+[[component-add-on-project-setup-howto]]
+Component add-on project setup how-to
+------------------------------------
+
+This how-to walks you through a complete setup for a project for
+developing, building and publishing your own Vaadin UI component
+add-ons. The goal here is not to teach how to write an add-on, but to
+make the process of setting up your project environment as smooth as
+possible. I hope this encourages you to try building and publishing your
+own add-ons :)
+
+[[goals-for-the-project-environment]]
+Goals for the project environment
+---------------------------------
+
+* Fully automated build with Maven
+* Allow anyone to re-build your project easily regardless of the IDE:s
+* Almost instant save-build-deploy-try cycle
+* Simple, but complete, project setup
+* Project publishing to GitHub
+* Easy publishing of the results to Vaadin Directory
+
+[[install-toolchain]]
+Install toolchain
+-----------------
+
+If you do not already have the following tools in use, install them:
+
+* Eclipse IDE for Java EE developers from http://www.eclipse.org (Indigo
+Service Release 1 was used in this how-to)
+* Google Chrome browser from https://www.google.com/chrome/ (other
+browsers will do, but Chrome is recommended)
+* Eclipse plugins: m4e-wtp, vaadin, egit (optional) and jrebel
+(optional) from Marketplace (just select Help->Marketplace... from the
+menu)
+
+[[create-a-new-widget-project]]
+Create a new widget project
+---------------------------
+
+Start project creation wizard: File -> New -> Other... -> "Maven
+Project"
+
+Give a proper name for your project and save it under workspace. For
+this example I am building a list widget and name it MyList.
+
+Ensure that your Maven archetype catalogs contain
+http://repo1.maven.org/maven2/archetype-catalog.xml as remote catalog
+and select it.
+
+Select vaadin-archetype-widget from the list.
+
+Give a proper name for the project. I use "org.vaadin" as group id as it
+can be used by anyone who wants to contribute non-commercial widgets to
+Vaadin project and name of the widget as artifact id in this case i use
+"mylist" as example. For a package name use "org.vaadin.mylist".
+
+Observe that pom.xml shows two errors. This is because m2e does not
+directly support gwt and vaadin -plugins. To fix the problem, choose the
+problems one by one and choose "ignore" quick fix. Then edit the pom.xml
+by changing all `<ignore></ignore>` tags to `<execute></execute>` to get the
+plugins to execute. Finally, clear the remaining "project configuration
+needs update" error with quickfix (that not surprisingly updates project
+configuration). In the end, pom.xml should look like
+https://raw.github.com/jojule/MyList/56ac906f9cc6442e0817eb0cc945eee023ff9001/pom.xml[this].
+
+Refactor the name of the component you are building.
+
+* Instead of using `MyComponent` and `VMyComponent`, use your own name. In
+this example I use `MyList` and `VMyList`.
+* Also change the theme directory name from
+`src/main/java/org/vaadin/mylist/gwt/public/mywidget` to
+`src/main/java/org/vaadin/mylist/gwt/public/mylist`
+* and update the reference in `MyWidgetSet.gwt.xml`.
+* Also rename `MyWidgetSet.gwt.xml` to `MyListWidgetSet.gwt.xml`
+* and update references in `pom.xml` and `web.xml`.
+
+Test that the project compiles and runs by running (Run -> Run as ... ->
+Maven Build...) maven goal "package jetty:run". If everything compiles
+fine and Jetty server starts, you can access the application at
+http://localhost:8080/mylist/. You should see "It works!" on the web
+page. Do not worry that the build takes a lot of time, we'll get back to
+it in a minute.
+
+Finally, if you prefer to use Git, create a repository for the project.
+You could simply choose "Share Project..." from the Project's Team menu.
+Choose "Use or create repository in parent folder" and click "Create
+Repository". Then, add project resources to commit. Choose pom.xml and
+src directory from Navigator view and select Team -> Add to Index. Then
+add the rest of the files (.settings, .project, .classpath and target)
+to .gitignore with Team -> Ignore. Finally, just do Team -> Commit.
+
+At this point - or later whenevery you are ready for it - you can
+publish the project to GitHub. Just go to github.com and create a new
+repository. Use MyList as the name for the repository. Then follow the
+instructions on the screen. In my case, I executed the following command
+line commands: `cd /Users/phoenix/Documents/workspace/mylist; git remote
+add origin git@github.com:jojule/MyList.git; git push -u origin master`.
+You can see the results
+https://github.com/jojule/MyList/tree/56ac906f9cc6442e0817eb0cc945eee023ff9001[at
+GitHub].
+
+[[save---build---deploy---try]]
+Save - Build - Deploy - Try
+---------------------------
+
+If it takes minutes each time from code change to seeing that change on
+the screen, you are not going to get your component ready anytime soon.
+To solve the issue, we use two tools: 1) Google GWT Developer Mode and
+2) JRebel. The first one is more important here as the GWT compilation
+step is the really slow step, but JRebel also helps as it gives you
+instant redeploy for the server-side changes.
+
+To enable JRebel, open project popup menu and choose JRebel -> Generate
+rebel.xml in `src/main/java`. Then click "Enable JRebel" on the JRebel tab
+for Maven run configuration for "jetty:run". Now when you make any
+changes to server-side code - for example to `WidgetTestApplication.java`
+- hit save and reload the browser pointing to
+http://localhost:8080/mylist/?restartApplication, the changes are
+appliead immediately. Even better - you can start the project with Debug
+As and add break points to the application.
+
+Client-side changes are more tricky as they are compiled from Java to
+JavaScript by GWT. To make those changes immediately you, must be
+running a GWT Devepment Mode. This is done by running Maven goal gwt:run
+instead of just pointing your web browser to the running application.
+Note that must be running both jetty:run and gwt:run concurrently.
+gwt:run starts application called "GWT Development Mode". From there you
+can launch your browser - or cut-n-paste URL to Chrome - if that is not
+your default browser. When the application is started, add
+`&restartApplication` parameter to the end of the URL to ensure that the
+server-side of the application is reloaded each time you reload the
+page. In this case, the full url is
+http://127.0.0.1:8080/mylist/?gwt.codesvr=127.0.0.1:9997&restartApplication.
+Try making a change to the client-side code (for example `VMyList.java`),
+hitting save and reloading the page to see how everything works
+together. You can also run gwt:run in Debug As to debug the client-side
+code.
+
+Now the "save - build - deploy - try" cycle has been reduced to almost
+instant for both client-side as well as server-side changes. Let the
+real development begin.
+
+[[developing-a-new-component-for-vaadin]]
+Developing a new component for Vaadin
+-------------------------------------
+
+Wait for an amazing idea, code like crazy, enjoy and POOOF, there it is
+- your own brand new component.
+
+If you need guidance with this,
+https://vaadin.com/book/-/page/gwt.html[Book of Vaadin] is a recommended
+reading :)
+
+For this example, I implemented a trivial list component. Take a look of
+1.0.0 version
+https://github.com/jojule/MyList/tree/496a8bdf629154a4da7b83c4a11979272959aa96[at
+GitHub], but do not expect too much :) To try it out just do: `git clone
+git@github.com:jojule/MyList.git; mvn package; mvn jetty:run` and point
+your web browser to http://localhost:8080/mylist/.
+
+[[packaging-and-submitting-the-widget-to-directory]]
+Packaging and submitting the widget to directory
+------------------------------------------------
+
+Set the version number in pom.xml
+
+Run Maven target "package" and you'll have a ready made package at
+target/mylist-1.0.0.jar ready for upload to vaadin directory.
+
+Go to https://vaadin.com/directory/my-components, select UI Component and
+click upload.
+
+Fill the form, preview and publish.