Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 133 insertions, 0 deletions

diff --git a/documentation/getting-started/getting-started-maven.asciidoc b/documentation/getting-started/getting-started-maven.asciidoc
new file mode 100644
index 0000000000..3914e973aa
--- /dev/null
+++ b/documentation/getting-started/getting-started-maven.asciidoc
@@ -0,0 +1,133 @@
+---
+title: Using Vaadin with Maven
+order: 6
+layout: page
+---
+
+[[getting-started.maven]]
+= Using Vaadin with Maven
+
+((("Maven", "creating a project", id="term.maven.creating", range="startofrange")))
+
+
+Maven is a commonly used build and dependency management system. The Vaadin core
+library and all Vaadin add-ons are available through Maven. You can use a Maven
+with a front-end from Eclipse or NetBeans, or by using the command-line as
+described in this section.
+
+In addition to regular Maven, you can use any Maven-compatible build or
+dependency management system, such as Ivy or Gradle. For Gradle, see the
+link:https://github.com/johndevs/gradle-vaadin-plugin[Gradle Vaadin Plugin].
+Vaadin Plugin for Eclipse uses Ivy for resolving dependencies in Vaadin
+projects, and it should provide you with the basic Ivy configuration.
+
+[[getting-started.maven.command-line]]
+== Working from Command-Line
+
+You can create a new Maven project with the following command (given in one
+line):
+
+[subs="normal"]
+----
+[prompt]#$# [command]#mvn# archetype:generate \
+   -DarchetypeGroupId=com.vaadin \
+   -DarchetypeArtifactId=[parameter]#vaadin-archetype-application# \
+   -DarchetypeVersion=[replaceable]#7.x.x# \
+   -DgroupId=[replaceable]#your.company# \
+   -DartifactId=[replaceable]#project-name# \
+   -Dversion=[replaceable]#0.1# \
+   -Dpackaging=war
+----
+The parameters are as follows:
+
+[parameter]#archetypeGroupId#:: The group ID of the archetype is [literal]#++com.vaadin++# for Vaadin
+archetypes.
+
+[parameter]#archetypeArtifactId#:: The archetype ID. Vaadin 7 currently supports
+[literal]#++vaadin-archetype-application++# archetype for server-side
+applications and [literal]#++vaadin-archetype-widget++# for client-side widget
+development projects.
+
++
+//TODO Vaadin 7: Not all these archetypes are supported
++
+////
+<itemizedlist> <listitem> <literal>vaadin-archetype-clean</literal> is a new project with a barebone skeleton for a regular Vaadin application. The <filename>pom.xml</filename> includes out-commented definitions for additional widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-widget</literal> is a skeleton for a project with custom widgets. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-sample</literal> is also for a project with custom widgets, but the skeleton includes the Color Picker example used in <xref linkend="gwt"/>. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-addon</literal> is for Vaadin add-on projects. It packages the add-on so that it can be published in Vaadin Directory. The archetype is for server-side add-ons and does not include definitions needed for building a widget set. If your add-on includes or requires other than the widgets in the Vaadin core library, you need to copy the required definitions from a POM of a <literal>vaadin-archetype-clean</literal> project. </listitem> </itemizedlist> <itemizedlist> <listitem> <literal>vaadin-archetype-touchkit</literal> is for projects using Vaadin TouchKit, described in <xref linkend="mobile"/>. Notice that this archetype uses the AGPL-licensed version of TouchKit, which requires that your project must also be licensed under the AGPL license. </listitem> </itemizedlist>
+////
+[parameter]#archetypeVersion#:: Version of the archetype to use. This should be [literal]#++LATEST++# for normal
+Vaadin releases. For prerelease versions it should be the exact version number,
+such as [literal]#++7.5.3++#.
+
+[parameter]#groupId#:: A Maven group ID for your project. It is normally your organization domain name
+in reverse order, such as com.example. The group ID is also used as a prefix for
+the Java package in the sources, so it should be Java compatible - only
+alphanumerics and an underscore.
+
+[parameter]#artifactId#:: Identifier of the artifact, that is, your project. The identifier may contain
+alphanumerics, minus, and underscore. It is appended to the group ID to obtain
+the Java package name for the sources. For example, if the group ID is
+com.example and artifact ID is myproject, the project sources would be placed in
+com.example.myproject package.
+
+[parameter]#version#:: Initial version number of your application. The number must obey the Maven
+version numbering format.
+
+[parameter]#packaging#:: How will the project be packaged. It is normally [literal]#++war++#.
+
+
+
+Creating a project can take a while as Maven fetches all the dependencies. The
+created project structure is shown in
+<<figure.getting-started.maven.archetype.created>>.
+
+[[figure.getting-started.maven.archetype.created]]
+.A New Vaadin Project with Maven
+image::img/maven-project-created.png[]
+
+
+[[getting-started.maven.compiling]]
+== Compiling and Running the Application
+
+((("Maven", "compiling", id="term.maven.compiling", range="startofrange")))
+
+
+Before the application can be deployed, it must be compiled and packaged as a
+WAR package. You can do this with the [literal]#++package++# goal as follows:
+
+[subs="normal"]
+----
+[prompt]#$# [command]#mvn# package
+----
+The location of the resulting WAR package should be displayed in the command
+output. You can then deploy it to your favorite application server.
+
+The easiest way to run Vaadin applications with Maven is to use the light-weight
+Jetty web server. After compiling the package, all you need to do is type:
+
+[subs="normal"]
+----
+[prompt]#$# [command]#mvn# jetty:run
+----
+The special goal starts the Jetty server in port 8080 and deploys the
+application. You can then open it in a web browser at
+http://localhost:8080/project-name.
+
+(((range="endofrange", startref="term.maven.compiling")))
+
+[[getting-started.maven.addons]]
+== Using Add-ons and Custom Widget Sets
+
+((("Maven", "using add-ons", id="term.maven.addons", range="startofrange")))
+
+
+If you use Vaadin add-ons that include a widget set or make your custom widgets,
+you need to enable widget set compilation in the POM. The required configuration
+is described in
+<<dummy/../../../framework/addons/addons-maven#addons.maven,"Using Add-ons in a
+Maven Project">>.
+
+
+(((range="endofrange", startref="term.maven.addons")))
+(((range="endofrange", startref="term.maven.creating")))
+
+