Author: jrthomerson
Date: Wed Jan 12 02:43:36 2011
New Revision: 1057976
URL: http://svn.apache.org/viewvc?rev=1057976&view=rev
Log:
more info for quickstart creation
Modified:
wicket/common/site/trunk/_site/atom.xml
wicket/common/site/trunk/_site/start/quickstart.html
wicket/common/site/trunk/start/quickstart.md
Modified: wicket/common/site/trunk/_site/atom.xml
URL:
http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/atom.xml?rev=1057976&r1=1057975&r2=1057976&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/atom.xml (original)
+++ wicket/common/site/trunk/_site/atom.xml Wed Jan 12 02:43:36 2011
@@ -4,7 +4,7 @@
<title>Apache Wicket</title>
<link href="http://wicket.apache.org/atom.xml"; rel="self"/>
<link href="http://wicket.apache.org/"/>
- <updated>2010-12-24T09:09:32-06:00</updated>
+ <updated>2011-01-11T20:42:35-06:00</updated>
<id>http://wicket.apache.org/</id>
<author>
<name>Apache Wicket</name>
Modified: wicket/common/site/trunk/_site/start/quickstart.html
URL:
http://svn.apache.org/viewvc/wicket/common/site/trunk/_site/start/quickstart.html?rev=1057976&r1=1057975&r2=1057976&view=diff
==============================================================================
--- wicket/common/site/trunk/_site/start/quickstart.html (original)
+++ wicket/common/site/trunk/_site/start/quickstart.html Wed Jan 12 02:43:36
2011
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
- <title>Apache Wicket - Get Started</title>
+ <title>Apache Wicket - Create a Wicket Quickstart</title>
<link rel="stylesheet" href="/css/screen.css" type="text/css"
media="screen" />
@@ -143,14 +143,14 @@
</div>
<div id="contentbody">
- <h1>Get Started</h1>
- <p>This guide is intended to get you up and running
& using Wicket within minutes.</p>
+ <h1>Create a Wicket Quickstart</h1>
+ <p>There are two really good reasons to create a Wicket
quickstart. The first is if you just want to get started using Wicket quickly.
The quickstart will set up a ready-to-use project in under a minute (depending
on your bandwidth). Another great reason to create a quickstart is to accompany
a bug report. If you report a bug in JIRA or on the mailing list, the core
developers may not be able to recreate it easily. In most cases, you’ll
be told “please create a quickstart and attach it to a JIRA issue”.
If you don’t know how to do that, don’t worry - just follow the
instructions below. (If you are submitting a quickstart for an issue report,
please be sure to read the subheading below - “Submitting a quickstart
for an issue report”</p>
-<p>It uses a Maven Archetype to create a Wicket QuickStart project, so
requires that <a href='http://maven.apache.org'>Maven 2</a> be installed &
configured beforehand.</p>
+<p>Quickstarts are made from a Maven archetype. So, you will need to have <a
href='http://maven.apache.org'>Maven 2</a> installed and working (from the
command line) before following this.</p>
-<p>This project provides a starting point for your Wicket project. If you are
looking for examples, please refer to the <em>wicket-example</em> projects
instead!</p>
+<p>Creating a quickstart provides only a very basic starting point for your
Wicket project. If you are looking for examples of how to use Wicket and its
various features, please refer to the <em>wicket-example</em> projects
instead!</p>
-<h2 id='creating_the_project'>Creating the project</h2>
+<h2 id='creating_the_project__with_maven'>Creating the project - with
Maven</h2>
<p>To create your project, copy and paste the command line generated after
typing in the groupId, artifactId and version.</p>
<style>
@@ -222,50 +222,48 @@
</div>
<h3 id='results'>Results</h3>
-<p>This will produce the following project structure/files</p>
-
-<pre><code>.\myproject
- | pom.xml
- |
- \---src
- +---main
- | +---java
- | | \---com
- | | \---mycompany
- | | HomePage.html
- | | HomePage.java
- | | WicketApplication.java
- | |
- | +---resources
- | | log4j.properties
- | |
- | \---webapp
- | \---WEB-INF
- | web.xml
+<p>This will produce the following project structure/files:</p>
+<div style='margin-left: 3em; border: 1px solid black'>
+<pre>
+ .\myproject
+ | pom.xml
|
- \---test
- \---java
- \---com
- \---mycompany
- Start.java</code></pre>
-
-<h2 id='use'>Use</h2>
-
-<p>Change into the project directory, then create a WAR file via <code>mvn
package</code> or build the project and run it under Jetty via <code>mvn
jetty:run</code>.</p>
-
-<h3 id='using_the_jetty_plugin'>Using the Jetty Plugin</h3>
+ \---src
+ +---main
+ | +---java
+ | | \---com
+ | | \---mycompany
+ | | HomePage.html
+ | | HomePage.java
+ | | WicketApplication.java
+ | |
+ | +---resources
+ | | log4j.properties
+ | |
+ | \---webapp
+ | \---WEB-INF
+ | web.xml
+ |
+ \---test
+ \---java
+ \---com
+ \---mycompany
+ Start.java
+</pre>
+</div>
+<h3 id='using_maven_quickstart_with_a_specific_ide'>Using Maven quickstart
with a specific IDE</h3>
-<p>This will compile the project then deploy it to an embeded instance of the
Jetty servlet engine, which will be use on port 8080, by default. As a result,
once running, your application will be available at <a
href='http:localhost:8080/myproject'>http:localhost:8080/myproject</a>.</p>
+<p>Maven has an integration with many IDEs. If you want to use your new
Maven-based Wicket quickstart with your favorite IDE, see one of these
instructions:</p>
-<p>See the <a href='http://www.mortbay.org/maven-plugin/index.html'>Jetty
plugin</a> documentation for configuration options, etc.</p>
+<h4 id='eclipse'>Eclipse</h4>
-<h3 id='using_with_a_specific_ide'>Using with a specific IDE</h3>
+<p>Change directory into the project that you just created. Now, run <code>mvn
eclipse:eclipse</code>. This will set up the .project, .settings, and
.classpath files that Eclipse requires.</p>
-<h4 id='eclipse'>Eclipse</h4>
+<p>Note that your workspace will have to have the classpath variable M2_REPO
set to point to the directory where your local Maven repository exists. You can
see this page for how to do that with Eclipse: <a
href='http://maven.apache.org/plugins/maven-eclipse-plugin/usage.html'>http://maven.apache.org/plugins/maven-eclipse-plugin/usage.html</a></p>
-<p>To create an Eclipse project, use <code>mvn eclipse:eclipse</code> inside
the project directory and import the project in your workspace (File ->
Import).</p>
+<p>Now, in Eclipse, you can choose “File” (menu), then
“Import”, then “Existing project”. Navigate to the
folder where your project exists and let Eclipse import it. The classpath
should be fully configured.</p>
-<p>Or alternatively install the <a
href='http://m2eclipse.codehaus.org/'>m2eclipse</a> or <a
href='http://www.eclipse.org/iam/'>Eclipse IAM</a> plugin and add the project
directly.</p>
+<p>Alternatively install the <a
href='http://m2eclipse.codehaus.org/'>m2eclipse</a> or <a
href='http://www.eclipse.org/iam/'>Eclipse IAM</a> plugin and add the project
directly.</p>
<h4 id='idea'>IDEA</h4>
@@ -278,6 +276,28 @@
<h3 id='more_examples'>More examples</h3>
<p>Many more information and examples can be found on our Wiki or <a
href='http://www.ralfebert.de/blog/wicket/wicket_eclipse_setup/'>here</a></p>
+
+<h2 id='using_your_new_project'>Using your new project</h2>
+
+<p>Wicket quickstart projects include a file named Start.java. If you open
this file in your IDE (after configuring the project in your IDE), you can run
it as a Java application. It will run an embedded Jetty instance that will run
your app on <a href='http://localhost:8080'>http://localhost:8080</a> Navigate
your browser to that address to see your app running.</p>
+
+<h3 id='using_the_jetty_plugin'>Using the Jetty Plugin</h3>
+
+<p>The Jetty plugin is also enabled by default in the quickstart. If you are
using Maven, you can change directory into the project and run the “mvn
jetty:run” command. This will compile the project and deploy it to an
embeded instance of the Jetty servlet engine, which will run on port 8080, by
default. As a result, once running, your application will be available at <a
href='http:localhost:8080/myproject'>http:localhost:8080/myproject</a>.</p>
+
+<p>See the <a href='http://www.mortbay.org/maven-plugin/index.html'>Jetty
plugin</a> documentation for configuration options, etc.</p>
+
+<h2 id='submitting_a_quickstart_for_an_issue_report'>Submitting a quickstart
for an issue report</h2>
+
+<h3 id='reproduce_the_problem'>Reproduce the problem</h3>
+
+<p>Assuming you have followed the instructions above, the quickstart is now
created and ready for you to develop. Now comes the “duplicate the
problem” part. Try to create pages or components that reproduce the
problem you were trying to report. You can run the Start.java class from your
IDE and go to <a href='http://localhost:8080/'>http://localhost:8080/</a> to
see your test application. If you run the Start.java class in your IDE’s
debug mode, you should be able to attach breakpoints and have automatic class
and markup reloading.</p>
+
+<p>If you can’t reproduce the problem - start looking at your own code.
Keep adding pieces from your code until either you reproduce the problem, or
else you’ve found the bug in your own code. A lot of times, you will find
the bug in your code just by trying to create a quickstart that demonstrates
the bug in ours.</p>
+
+<h3 id='clean_up_the_quickstart_and_submit_it'>Clean up the quickstart and
submit it</h3>
+
+<p>Once you have reproduced the desired behavior in your quickstart, it would
be best to make it as small as possible before submitting. The best way to do
this is to run the “mvn clean” command from the project directory.
Then zip (or tar and gzip) the whole directory up and submit the zip (or tgz)
file. (The mvn clean command removes all of the compiled classes and generated
artifacts, generally in your “target” directory, leaving only the
actual source.)</p>
</div>
<div id="clearer"></div>
<div id="footer"><span>
Modified: wicket/common/site/trunk/start/quickstart.md
URL:
http://svn.apache.org/viewvc/wicket/common/site/trunk/start/quickstart.md?rev=1057976&r1=1057975&r2=1057976&view=diff
==============================================================================
--- wicket/common/site/trunk/start/quickstart.md (original)
+++ wicket/common/site/trunk/start/quickstart.md Wed Jan 12 02:43:36 2011
@@ -1,18 +1,28 @@
---
layout: default
-title: Get Started
+title: Create a Wicket Quickstart
---
-This guide is intended to get you up and running & using Wicket within
-minutes.
+There are two really good reasons to create a Wicket quickstart. The first is
if
+you just want to get started using Wicket quickly. The quickstart will set up
a
+ready-to-use project in under a minute (depending on your bandwidth). Another
+great reason to create a quickstart is to accompany a bug report. If you
report
+a bug in JIRA or on the mailing list, the core developers may not be able to
+recreate it easily. In most cases, you'll be told "please create a quickstart
and
+attach it to a JIRA issue". If you don't know how to do that, don't worry -
just
+follow the instructions below. (If you are submitting a quickstart for an
issue
+report, please be sure to read the subheading below - "Submitting a quickstart
+for an issue report"
+
+Quickstarts are made from a Maven archetype. So, you will need to have
+[Maven 2](http://maven.apache.org) installed and working (from the command
line)
+before following this.
+
+Creating a quickstart provides only a very basic starting point for your Wicket
+project. If you are looking for examples of how to use Wicket and its various
+features, please refer to the *wicket-example* projects instead!
-It uses a Maven Archetype to create a Wicket QuickStart project, so requires
-that [Maven 2](http://maven.apache.org) be installed & configured beforehand.
-
-This project provides a starting point for your Wicket project. If you are
-looking for examples, please refer to the *wicket-example* projects instead!
-
-## Creating the project ##
+## Creating the project - with Maven
To create your project, copy and paste the command line generated after
typing in the groupId, artifactId and version.
@@ -75,8 +85,10 @@ typing in the groupId, artifactId and ve
### Results
-This will produce the following project structure/files
+This will produce the following project structure/files:
+<div style="margin-left: 3em; border: 1px solid black">
+<pre>
.\myproject
| pom.xml
|
@@ -101,30 +113,27 @@ This will produce the following project
\---com
\---mycompany
Start.java
+</pre>
+</div>
-## Use
-
-Change into the project directory, then create a WAR file via `mvn package`
-or build the project and run it under Jetty via `mvn jetty:run`.
-
-### Using the Jetty Plugin
+### Using Maven quickstart with a specific IDE
-This will compile the project then deploy it to an embeded instance of the
-Jetty servlet engine, which will be use on port 8080, by default. As a
-result, once running, your application will be available at
-<http:localhost:8080/myproject>.
+Maven has an integration with many IDEs. If you want to use your new
Maven-based
+Wicket quickstart with your favorite IDE, see one of these instructions:
-See the [Jetty plugin](http://www.mortbay.org/maven-plugin/index.html)
-documentation for configuration options, etc.
+#### Eclipse
-### Using with a specific IDE
+Change directory into the project that you just created. Now, run
+`mvn eclipse:eclipse`. This will set up the .project, .settings, and
.classpath
+files that Eclipse requires.
-#### Eclipse
+Note that your workspace will have to have the classpath variable M2_REPO set
to point to the directory where your local Maven repository exists. You can
see this page for how to do that with Eclipse:
<http://maven.apache.org/plugins/maven-eclipse-plugin/usage.html>
-To create an Eclipse project, use `mvn eclipse:eclipse` inside the project
-directory and import the project in your workspace (File -> Import).
+Now, in Eclipse, you can choose "File" (menu), then "Import", then "Existing
project".
+Navigate to the folder where your project exists and let Eclipse import it.
The classpath should
+be fully configured.
-Or alternatively install the [m2eclipse](http://m2eclipse.codehaus.org/) or
+Alternatively install the [m2eclipse](http://m2eclipse.codehaus.org/) or
[Eclipse IAM](http://www.eclipse.org/iam/) plugin and add the project
directly.
@@ -141,3 +150,39 @@ To create a NetBeans project, just open
Many more information and examples can be found on our Wiki or
[here](http://www.ralfebert.de/blog/wicket/wicket_eclipse_setup/)
+
+## Using your new project
+
+Wicket quickstart projects include a file named Start.java. If you open this
file in
+your IDE (after configuring the project in your IDE), you can run it as a Java
application.
+It will run an embedded Jetty instance that will run your app on
<http://localhost:8080>
+Navigate your browser to that address to see your app running.
+
+### Using the Jetty Plugin
+
+The Jetty plugin is also enabled by default in the quickstart. If you are
using Maven,
+you can change directory into the project and run the "mvn jetty:run" command.
This will
+compile the project and deploy it to an embeded instance of the Jetty servlet
engine,
+which will run on port 8080, by default. As a result, once running, your
application will be available at <http:localhost:8080/myproject>.
+
+See the [Jetty plugin](http://www.mortbay.org/maven-plugin/index.html)
+documentation for configuration options, etc.
+
+## Submitting a quickstart for an issue report
+
+### Reproduce the problem
+
+Assuming you have followed the instructions above, the quickstart is now
created and ready for you to develop. Now comes the "duplicate the problem"
part. Try to create pages or components that reproduce the problem you were
trying to report. You can run the Start.java class from your
+IDE and go to <http://localhost:8080/> to see your test application. If you
run the Start.java class
+in your IDE's debug mode, you should be able to attach breakpoints and have
automatic class and
+markup reloading.
+
+If you can't reproduce the problem - start looking at your own code. Keep
adding pieces from
+your code until either you reproduce the problem, or else you've found the bug
in your own code.
+A lot of times, you will find the bug in your code just by trying to create a
quickstart that
+demonstrates the bug in ours.
+
+### Clean up the quickstart and submit it
+
+Once you have reproduced the desired behavior in your quickstart, it would be
best to make it as small as possible before submitting. The best way to do
this is to run the "mvn clean" command from the project directory. Then zip
(or tar and gzip) the whole directory up and submit the zip (or tgz) file.
(The mvn clean command removes all of the compiled classes and generated
artifacts, generally in your "target" directory, leaving only the actual
source.)
+
