You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by eh...@apache.org on 2007/06/14 06:46:30 UTC
svn commit: r547118 - in
/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard:
AbstractWizardModel.java IWizardModel.java LastButton.java Wizard.java
WizardModel.java WizardStep.java
Author: ehillenius
Date: Wed Jun 13 21:46:29 2007
New Revision: 547118
URL: http://svn.apache.org/viewvc?view=rev&rev=547118
Log:
more abstractions, tweaks and doc improvements for the wizard component
Added:
incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/AbstractWizardModel.java
Modified:
incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/IWizardModel.java
incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/LastButton.java
incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/Wizard.java
incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardModel.java
incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardStep.java
Added: incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/AbstractWizardModel.java
URL: http://svn.apache.org/viewvc/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/AbstractWizardModel.java?view=auto&rev=547118
==============================================================================
--- incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/AbstractWizardModel.java (added)
+++ incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/AbstractWizardModel.java Wed Jun 13 21:46:29 2007
@@ -0,0 +1,185 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.wicket.extensions.wizard;
+
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * Abstract wizard model that provides an implementation for handling
+ * {@link IWizardModelListener wizard model listeners} and provides base
+ * implementations of many methods. If you want to provide a custom
+ * implementation of {@link IWizardModel}, it is recommended you start by
+ * overriding this class.
+ *
+ * @author eelcohillenius
+ */
+public abstract class AbstractWizardModel implements IWizardModel
+{
+
+ /** Whether cancel functionality is available. */
+ private boolean cancelVisible = true;
+
+ /** Whether the last button should be shown at all; false by default. */
+ private boolean lastVisible = false;
+
+ /** Listeners for {@link IWizardModelListener model events}. */
+ private final List wizardModelListeners = new ArrayList(1);
+
+ /**
+ * Construct.
+ */
+ public AbstractWizardModel()
+ {
+ }
+
+ /**
+ * Adds a wizard model listener.
+ *
+ * @param listener
+ * The listener to add
+ */
+ public final void addListener(IWizardModelListener listener)
+ {
+ this.wizardModelListeners.add(listener);
+ }
+
+ /**
+ * This implementation just fires
+ * {@link IWizardModelListener#onCancel() a cancel event}. Though this
+ * isn't a very strong contract, it gives all the power to the user of this
+ * model.
+ *
+ * @see IWizardModel#cancel()
+ */
+ public void cancel()
+ {
+ fireWizardCancelled();
+ }
+
+ /**
+ * This implementation just fires
+ * {@link IWizardModelListener#onFinish() a finish event}. Though this
+ * isn't a very strong contract, it gives all the power to the user of this
+ * model.
+ *
+ * @see IWizardModel#finish()
+ */
+ public void finish()
+ {
+ fireWizardFinished();
+ }
+
+ /**
+ * Gets whether cancel functionality is available.
+ *
+ * @return Whether cancel functionality is available
+ */
+ public boolean isCancelVisible()
+ {
+ return cancelVisible;
+ }
+
+ /**
+ * Checks if the last button should be displayed. This method should only
+ * return true if {@link IWizardModel#isLastAvailable} can return true at
+ * any point. Returning false will prevent the last button from appearing on
+ * the wizard at all.
+ *
+ * @return <tt>true</tt> if the previou last should be displayed,
+ * <tt>false</tt> otherwise.
+ */
+ public boolean isLastVisible()
+ {
+ return lastVisible;
+ }
+
+ /**
+ * Removes a wizard model listener.
+ *
+ * @param listener
+ * The listener to remove
+ */
+ public final void removeListener(IWizardModelListener listener)
+ {
+ this.wizardModelListeners.remove(listener);
+ }
+
+ /**
+ * Sets whether cancel functionality is available.
+ *
+ * @param cancelVisible
+ * Whether cancel functionality is available
+ */
+ public void setCancelVisible(boolean cancelVisible)
+ {
+ this.cancelVisible = cancelVisible;
+ }
+
+ /**
+ * Configures if the last button should be displayed.
+ *
+ * @param lastVisible
+ * <tt>true</tt> to display the last button, <tt>false</tt>
+ * otherwise.
+ * @see #isLastVisible
+ */
+ public void setLastVisible(boolean lastVisible)
+ {
+ this.lastVisible = lastVisible;
+ }
+
+ /**
+ * Notify listeners that the active step has changed.
+ *
+ * @param step
+ * The new step
+ */
+ protected final void fireActiveStepChanged(IWizardStep step)
+ {
+ for (Iterator i = wizardModelListeners.iterator(); i.hasNext();)
+ {
+ IWizardModelListener listener = (IWizardModelListener)i.next();
+ listener.onActiveStepChanged(step);
+ }
+ }
+
+ /**
+ * Notify listeners that the wizard is finished.
+ */
+ protected final void fireWizardCancelled()
+ {
+ for (Iterator i = wizardModelListeners.iterator(); i.hasNext();)
+ {
+ IWizardModelListener listener = (IWizardModelListener)i.next();
+ listener.onCancel();
+ }
+ }
+
+ /**
+ * Notify listeners that the wizard is finished.
+ */
+ protected final void fireWizardFinished()
+ {
+ for (Iterator i = wizardModelListeners.iterator(); i.hasNext();)
+ {
+ IWizardModelListener listener = (IWizardModelListener)i.next();
+ listener.onFinish();
+ }
+ }
+}
Modified: incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/IWizardModel.java
URL: http://svn.apache.org/viewvc/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/IWizardModel.java?view=diff&rev=547118&r1=547117&r2=547118
==============================================================================
--- incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/IWizardModel.java (original)
+++ incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/IWizardModel.java Wed Jun 13 21:46:29 2007
@@ -20,8 +20,6 @@
import org.apache.wicket.IClusterable;
-
-
/**
* This interface defines the model for wizards. This model knows about the
* wizard's steps and the transitions between them, and it holds a reference to
@@ -39,7 +37,8 @@
* Typically, you would use
* {@link WizardModel the default implementation of this interface}, but if you
* need to do more sophisticated stuff, like branching etc, you can consider
- * creating your own implementation.
+ * creating your own implementation. In that case, it is recommended you start
+ * by extending from {@link AbstractWizardModel}.
* </p>
*
* <p>
@@ -47,6 +46,7 @@
* served as a valuable source of inspiration.
* </p>
*
+ * @see AbstractWizardModel
* @see WizardModel
*
* @author Eelco Hillenius
@@ -118,7 +118,6 @@
*/
boolean isLastVisible();
-
/**
* Gets whether the next button should be enabled.
*
@@ -135,19 +134,25 @@
/**
* Takes the model to the last step in the wizard. This method must only be
- * called if {@link #isLastAvailable} returns <tt>true</tt>.
+ * called if {@link #isLastAvailable} returns <tt>true</tt>. Implementors
+ * should notify {@link IWizardModelListener listeners} through calling
+ * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
*/
- void lastStep();
+ void last();
/**
- * Increments the model to the next step. This method must only be called
- * if {@link #isNextAvailable} returns <tt>true</tt>.
+ * Increments the model to the next step. This method must only be called if
+ * {@link #isNextAvailable} returns <tt>true</tt>. Implementors should
+ * notify {@link IWizardModelListener listeners} through calling
+ * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
*/
void next();
/**
* Takes the model to the previous step.This method must only be called if
- * {@link #isPreviousAvailable} returns <tt>true</tt>.
+ * {@link #isPreviousAvailable} returns <tt>true</tt>. Implementors
+ * should notify {@link IWizardModelListener listeners} through calling
+ * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
*/
void previous();
@@ -160,15 +165,20 @@
void removeListener(IWizardModelListener listener);
/**
- * Resets the model, setting it to the first step.
+ * Resets the model, setting it to the first step. Implementors should
+ * notify {@link IWizardModelListener listeners} through calling
+ * {@link IWizardModelListener#onActiveStepChanged(IWizardStep)}.
*/
void reset();
/**
* Returns an iterator over all the steps in the model. The iteration order
- * is not guarenteed to the be the order of traversal.
+ * is not guarenteed to the be the order of traversal. This is an optional
+ * operation; dynamic models can just return null, and should call init the
+ * first time a step is encountered right before rendering it.
*
- * @return an iterator over all the steps of the model
+ * @return an iterator over all the steps of the model or null if the wizard
+ * model is not static
*/
Iterator stepIterator();
}
Modified: incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/LastButton.java
URL: http://svn.apache.org/viewvc/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/LastButton.java?view=diff&rev=547118&r1=547117&r2=547118
==============================================================================
--- incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/LastButton.java (original)
+++ incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/LastButton.java Wed Jun 13 21:46:29 2007
@@ -19,7 +19,7 @@
/**
* Models a 'last' button in the wizard. When pressed, it calls
* {@link IWizardStep#applyState()} on the active wizard step, and then moves to
- * the last step in the model with {@link IWizardModel#lastStep()}.
+ * the last step in the model with {@link IWizardModel#last()}.
*
* @author Eelco Hillenius
*/
@@ -63,6 +63,6 @@
{
IWizardModel wizardModel = getWizardModel();
wizardModel.getActiveStep().applyState();
- wizardModel.lastStep();
+ wizardModel.last();
}
}
Modified: incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/Wizard.java
URL: http://svn.apache.org/viewvc/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/Wizard.java?view=diff&rev=547118&r1=547117&r2=547118
==============================================================================
--- incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/Wizard.java (original)
+++ incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/Wizard.java Wed Jun 13 21:46:29 2007
@@ -28,22 +28,22 @@
/**
- * A wizard is a dialog component that takes it's users through a number of
- * predefined steps. It has common functionality like a next, previous, finish
+ * A wizard is a dialog component that takes users through a number of steps to
+ * complete a task. It has common functionality like a next, previous, finish
* and cancel button, and it uses a {@link IWizardModel} to navigate through the
* steps.
+ * <p>
+ * Before you can use the wizard component, it needs to be initialized with a
+ * model. You do this by calling {@link #init(IWizardModel)} with the wizard
+ * model you intent to use.
+ * </p>
*
* <p>
* This default implementation should be useful for basic cases, if the layout
* is exactly what you need. If you want to provide your own layout and/ or have
* more or less components (e.g. you want to additionally provide an overview
* component), you can override this class and add the components you want
- * yourself.
- * </p>
- * <p>
- * If that's still not enough flexiblity for you, but you want to use the
- * {@link IWizardModel wizard model} and {@link IWizardStep wizard step}
- * functionality provided in this package, you can provde a custom wizard
+ * yourself using methods like {@link #newButtonBar(String)} et-cetera.
* </p>
*
* @author Eelco Hillenius
@@ -275,9 +275,13 @@
wizardModel.addListener(this);
- for (Iterator iter = wizardModel.stepIterator(); iter.hasNext();)
+ Iterator stepsIterator = wizardModel.stepIterator();
+ if (stepsIterator != null)
{
- ((IWizardStep)iter.next()).init(wizardModel);
+ while (stepsIterator.hasNext())
+ {
+ ((IWizardStep)stepsIterator.next()).init(wizardModel);
+ }
}
// reset model to prepare for action
Modified: incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardModel.java
URL: http://svn.apache.org/viewvc/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardModel.java?view=diff&rev=547118&r1=547117&r2=547118
==============================================================================
--- incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardModel.java (original)
+++ incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardModel.java Wed Jun 13 21:46:29 2007
@@ -25,11 +25,15 @@
/**
- * Default implementation of {@link IWizardModel}.
+ * Default implementation of {@link IWizardModel}, which models a semi-static
+ * wizard. This means that all steps should be known upfront, and added to the
+ * model on construction. Steps can be optional by using {@link ICondition}.
+ * The wizard is initialized with a wizard model through calling method
+ * {@link Wizard#init(IWizardModel)}.
* <p>
* Steps can be added to this model directly using either the
* {@link #add(IWizardStep) normal add method} or
- * {@link #add(IWizardStep, org.apache.wicket.extensions.wizard.WizardModel.ICondition) the conditional add method}.
+ * {@link #add(IWizardStep, ICondition) the conditional add method}.
* </p>
*
* <p>
@@ -39,7 +43,7 @@
*
* @author Eelco Hillenius
*/
-public class WizardModel implements IWizardModel
+public class WizardModel extends AbstractWizardModel
{
/**
* Interface for conditional displaying of wizard steps.
@@ -79,24 +83,15 @@
/** The currently active step. */
private IWizardStep activeStep;
- /** Whether cancel functionality is available. */
- private boolean cancelVisible = true;
-
/** Conditions with steps. */
private List conditions = new ArrayList();
/** State history. */
private final ArrayListStack history = new ArrayListStack();
- /** Whether the last button should be shown at all; false by default. */
- private boolean lastVisible = false;
-
/** The wizard steps. */
private List steps = new ArrayList();
- /** Listeners for {@link IWizardModelListener model events}. */
- private final List wizardModelListeners = new ArrayList(1);
-
/**
* Construct.
*/
@@ -137,43 +132,6 @@
}
/**
- * Adds a wizard model listener.
- *
- * @param listener
- * The listener to add
- */
- public final void addListener(IWizardModelListener listener)
- {
- this.wizardModelListeners.add(listener);
- }
-
- /**
- * This implementation just fires
- * {@link IWizardModelListener#onCancel() a cancel event}. Though this
- * isn't a very strong contract, it gives all the power to the user of this
- * model.
- *
- * @see org.apache.wicket.extensions.wizard.IWizardModel#cancel()
- */
- public void cancel()
- {
- fireWizardCancelled();
- }
-
- /**
- * This implementation just fires
- * {@link IWizardModelListener#onFinish() a finish event}. Though this
- * isn't a very strong contract, it gives all the power to the user of this
- * model.
- *
- * @see org.apache.wicket.extensions.wizard.IWizardModel#finish()
- */
- public void finish()
- {
- fireWizardFinished();
- }
-
- /**
* Gets the current active step the wizard should display.
*
* @return the active step.
@@ -184,21 +142,11 @@
}
/**
- * Gets whether cancel functionality is available.
- *
- * @return Whether cancel functionality is available
- */
- public boolean isCancelVisible()
- {
- return cancelVisible;
- }
-
- /**
* Checks if the last button should be enabled.
*
* @return <tt>true</tt> if the last button should be enabled,
* <tt>false</tt> otherwise.
- * @see #isLastVisible
+ * @see IWizardModel#isLastVisible
*/
public boolean isLastAvailable()
{
@@ -214,20 +162,6 @@
}
/**
- * Checks if the last button should be displayed. This method should only
- * return true if the {@link #isLastAvailable} will return true at any
- * point. Returning false will prevent the last button from appearing on the
- * wizard at all.
- *
- * @return <tt>true</tt> if the previou last should be displayed,
- * <tt>false</tt> otherwise.
- */
- public boolean isLastVisible()
- {
- return lastVisible;
- }
-
- /**
* Checks if the next button should be enabled.
*
* @return <tt>true</tt> if the next button should be enabled,
@@ -250,9 +184,9 @@
}
/**
- * @see org.apache.wicket.extensions.wizard.IWizardModel#lastStep()
+ * @see org.apache.wicket.extensions.wizard.IWizardModel#last()
*/
- public void lastStep()
+ public void last()
{
history.push(getActiveStep());
IWizardStep lastStep = findLastStep();
@@ -279,17 +213,6 @@
}
/**
- * Removes a wizard model listener.
- *
- * @param listener
- * The listener to remove
- */
- public final void removeListener(IWizardModelListener listener)
- {
- this.wizardModelListeners.remove(listener);
- }
-
- /**
* @see org.apache.wicket.extensions.wizard.IWizardModel#reset()
*/
public void reset()
@@ -311,38 +234,14 @@
{
return;
}
- IWizardStep old = this.activeStep;
+
this.activeStep = step;
fireActiveStepChanged(step);
}
/**
- * Sets whether cancel functionality is available.
- *
- * @param cancelVisible
- * Whether cancel functionality is available
- */
- public void setCancelVisible(boolean cancelVisible)
- {
- this.cancelVisible = cancelVisible;
- }
-
- /**
- * Configures if the last button should be displayed.
- *
- * @param lastVisible
- * <tt>true</tt> to display the last button, <tt>false</tt>
- * otherwise.
- * @see #isLastVisible
- */
- public void setLastVisible(boolean lastVisible)
- {
- this.lastVisible = lastVisible;
- }
-
- /**
- * @see org.apache.wicket.extensions.wizard.IWizardModel#stepIterator()
+ * @see IWizardModel#stepIterator()
*/
public final Iterator stepIterator()
{
@@ -408,44 +307,5 @@
}
throw new IllegalStateException("Wizard contains no more visible steps");
- }
-
- /**
- * Notify listeners that the active step has changed.
- *
- * @param step
- * The new step
- */
- protected final void fireActiveStepChanged(IWizardStep step)
- {
- for (Iterator i = wizardModelListeners.iterator(); i.hasNext();)
- {
- IWizardModelListener listener = (IWizardModelListener)i.next();
- listener.onActiveStepChanged(step);
- }
- }
-
- /**
- * Notify listeners that the wizard is finished.
- */
- protected final void fireWizardCancelled()
- {
- for (Iterator i = wizardModelListeners.iterator(); i.hasNext();)
- {
- IWizardModelListener listener = (IWizardModelListener)i.next();
- listener.onCancel();
- }
- }
-
- /**
- * Notify listeners that the wizard is finished.
- */
- protected final void fireWizardFinished()
- {
- for (Iterator i = wizardModelListeners.iterator(); i.hasNext();)
- {
- IWizardModelListener listener = (IWizardModelListener)i.next();
- listener.onFinish();
- }
}
}
Modified: incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardStep.java
URL: http://svn.apache.org/viewvc/incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardStep.java?view=diff&rev=547118&r1=547117&r2=547118
==============================================================================
--- incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardStep.java (original)
+++ incubator/wicket/trunk/jdk-1.4/wicket-extensions/src/main/java/org/apache/wicket/extensions/wizard/WizardStep.java Wed Jun 13 21:46:29 2007
@@ -58,18 +58,18 @@
* HTML (defined in e.g. file x/NewUserWizard$UserNameStep.html):
*
* <pre>
- * <wicket:panel>
- * <table>
- * <tr>
- * <td><wicket:message key="username">Username</wicket:message></td>
- * <td><input type="text" wicket:id="user.userName" /></td>
- * </tr>
- * <tr>
- * <td><wicket:message key="email">Email Adress</wicket:message></td>
- * <td><input type="text" wicket:id="user.email" /></td>
- * </tr>
- * </table>
- * </wicket:panel>
+ * <wicket:panel>
+ * <table>
+ * <tr>
+ * <td><wicket:message key="username">Username</wicket:message></td>
+ * <td><input type="text" wicket:id="user.userName" /></td>
+ * </tr>
+ * <tr>
+ * <td><wicket:message key="email">Email Adress</wicket:message></td>
+ * <td><input type="text" wicket:id="user.email" /></td>
+ * </tr>
+ * </table>
+ * </wicket:panel>
* </pre>
*
* </p>