/*
* 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.Arrays;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import org.apache.wicket.Component;
import org.apache.wicket.extensions.wizard.dynamic.DynamicWizardModel;
import org.apache.wicket.markup.html.basic.Label;
import org.apache.wicket.markup.html.form.Form;
import org.apache.wicket.markup.html.form.FormComponent;
import org.apache.wicket.markup.html.form.validation.IFormValidator;
import org.apache.wicket.markup.html.panel.Panel;
import org.apache.wicket.model.CompoundPropertyModel;
import org.apache.wicket.model.IModel;
import org.apache.wicket.model.Model;
/**
* default implementation of {@link IWizardStep}. It is also a panel, which is used as the view
* component.
*
* <p>
* And example of a custom step with a panel follows.
*
* Java (defined e.g. in class x.NewUserWizard):
*
* <pre>
* private final class UserNameStep extends WizardStep
* {
* public UserNameStep()
* {
* super(new ResourceModel("username.title"), new ResourceModel("username.summary"));
* add(new RequiredTextField("user.userName"));
* add(new RequiredTextField("user.email").add(EmailAddressValidator.getInstance()));
* }
* }
* </pre>
*
* 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 Address</wicket:message></td>
* <td><input type="text" wicket:id="user.email" /></td>
* </tr>
* </table>
* </wicket:panel>
* </pre>
*
* </p>
*
* @author Eelco Hillenius
*/
public class WizardStep extends Panel implements IWizardStep
{
/**
* Wraps form validators for this step such that they are only executed when this step is
* active.
*/
private final class FormValidatorWrapper implements IFormValidator
{
private static final long serialVersionUID = 1L;
private final List<IFormValidator> validators = new ArrayList<>();
/**
* Adds a form validator.
*
* @param validator
* The validator to add
*/
public final void add(final IFormValidator validator)
{
validators.add(validator);
}
/**
* @see org.apache.wicket.markup.html.form.validation.IFormValidator#getDependentFormComponents()
*/
@Override
public FormComponent<?>[] getDependentFormComponents()
{
if (isActiveStep())
{
Set<Component> components = new HashSet<>();
for (IFormValidator v : validators)
{
FormComponent<?>[] dependentComponents = v.getDependentFormComponents();
if (dependentComponents != null)
{
int len = dependentComponents.length;
components.addAll(Arrays.asList(dependentComponents).subList(0, len));
}
}
return components.toArray(new FormComponent[components.size()]);
}
return null;
}
/**
* @see org.apache.wicket.markup.html.form.validation.IFormValidator#validate(org.apache.wicket.markup.html.form.Form)
*/
@Override
public void validate(final Form<?> form)
{
if (isActiveStep())
{
for (IFormValidator v : validators)
{
v.validate(form);
}
}
}
/**
* @return whether the step this wrapper is part of is the current step
*/
private boolean isActiveStep()
{
return (wizardModel.getActiveStep().equals(WizardStep.this));
}
}
/**
* Default header for wizards.
*/
private final class Header extends Panel
{
private static final long serialVersionUID = 1L;
/**
* Construct.
*
* @param id
* The component id
* @param wizard
* The containing wizard
*/
public Header(final String id, final IWizard wizard)
{
super(id);
setDefaultModel(new CompoundPropertyModel<>(wizard));
add(new Label("title", WizardStep.this::getTitle));
add(new Label("summary", WizardStep.this::getSummary));
}
}
private static final long serialVersionUID = 1L;
/**
* Marks this step as being fully configured. Only when this is <tt>true</tt> can the wizard
* progress. True by default as that works best with normal forms. Clients can set this to false
* if some intermediate step, like a file upload, needs to be completed before the wizard may
* progress.
*/
private boolean complete = true;
/**
* A summary of this step, or some usage advice.
*/
private IModel<String> summary;
/**
* The title of this step.
*/
private IModel<String> title;
/**
* The wizard model.
*/
private IWizardModel wizardModel;
/**
* The wrapper of {@link IFormValidator}s for this step.
*/
private FormValidatorWrapper formValidatorWrapper = new FormValidatorWrapper();
/**
* Construct without a title and a summary. Useful for when you provide a custom header by
* overiding {@link #getHeader(String, Component, IWizard)}.
*/
public WizardStep()
{
super(Wizard.VIEW_ID);
}
/**
* Creates a new step with the specified title and summary. The title and summary are displayed
* in the wizard title block while this step is active.
*
* @param title
* the title of this step.
* @param summary
* a brief summary of this step or some usage guidelines.
*/
public WizardStep(final IModel<String> title, final IModel<String> summary)
{
this(title, summary, null);
}
/**
* Creates a new step with the specified title and summary. The title and summary are displayed
* in the wizard title block while this step is active.
*
* @param title
* the title of this step.
* @param summary
* a brief summary of this step or some usage guidelines.
* @param model
* Any model which is to be used for this step
*/
public WizardStep(final IModel<String> title, final IModel<String> summary,
final IModel<?> model)
{
super(Wizard.VIEW_ID, model);
this.title = wrap(title);
this.summary = wrap(summary);
}
/**
* Creates a new step with the specified title and summary. The title and summary are displayed
* in the wizard title block while this step is active.
*
* @param title
* the title of this step.
* @param summary
* a brief summary of this step or some usage guidelines.
*/
public WizardStep(final String title, final String summary)
{
this(title, summary, null);
}
/**
* Creates a new step with the specified title and summary. The title and summary are displayed
* in the wizard title block while this step is active.
*
* @param title
* the title of this step.
* @param summary
* a brief summary of this step or some usage guidelines.
* @param model
* Any model which is to be used for this step
*/
public WizardStep(final String title, final String summary, final IModel<?> model)
{
this(new Model<String>(title), new Model<>(summary), model);
}
/**
* Adds a form validator.
*
* @param validator
*/
public final void add(final IFormValidator validator)
{
formValidatorWrapper.add(validator);
}
/**
* @see org.apache.wicket.extensions.wizard.IWizardStep#applyState()
*/
@Override
public void applyState()
{
}
/**
* @see org.apache.wicket.extensions.wizard.IWizardStep#getHeader(java.lang.String,
* org.apache.wicket.Component, org.apache.wicket.extensions.wizard.IWizard)
*/
@Override
public Component getHeader(final String id, final Component parent, final IWizard wizard)
{
return new Header(id, wizard);
}
/**
* Gets the summary of this step. This will be displayed in the title of the wizard while this
* step is active. The summary is typically an overview of the step or some usage guidelines for
* the user.
*
* @return the summary of this step.
*/
public String getSummary()
{
return (summary != null) ? summary.getObject() : null;
}
/**
* Gets the title of this step.
*
* @return the title of this step.
*/
public String getTitle()
{
return (title != null) ? title.getObject() : null;
}
/**
* @see org.apache.wicket.extensions.wizard.IWizardStep#getView(java.lang.String,
* org.apache.wicket.Component, org.apache.wicket.extensions.wizard.IWizard)
*/
@Override
public Component getView(final String id, final Component parent, final IWizard wizard)
{
return this;
}
/**
* Called to initialize the step. When this method is called depends on the kind of wizard model
* that is used.
*
* The {@link WizardModel static wizard model} knows all the steps upfront and initializes themm
* when starting up. This method will be called when the wizard is {@link #init(IWizardModel)
* initializing}.
*
* The {@link DynamicWizardModel dynamic wizard model} initializes steps every time they are
* encountered.
*
* This method sets the wizard model and then calls template method
* {@link #onInit(IWizardModel)}
*
* @param wizardModel
* the model to which the step belongs.
*/
@Override
public final void init(final IWizardModel wizardModel)
{
this.wizardModel = wizardModel;
onInit(wizardModel);
}
/**
* Checks if this step is compete. This method should return true if the wizard can proceed to
* the next step. This property is bound and changes can be made at anytime by calling
* {@link #setComplete(boolean)} .
*
* @return <tt>true</tt> if the wizard can proceed from this step, <tt>false</tt> otherwise.
* @see #setComplete
*/
@Override
public boolean isComplete()
{
return complete;
}
/**
* Marks this step as compete. The wizard will not be able to proceed from this step until this
* property is configured to <tt>true</tt>.
*
* @param complete
* <tt>true</tt> to allow the wizard to proceed, <tt>false</tt> otherwise.
* @see #isComplete
*/
public void setComplete(final boolean complete)
{
this.complete = complete;
}
/**
* Sets summary.
*
* @param summary
* summary
*/
public void setSummaryModel(final IModel<String> summary)
{
this.summary = wrap(summary);
}
/**
* Sets title.
*
* @param title
* title
*/
public void setTitleModel(final IModel<String> title)
{
this.title = wrap(title);
}
/**
* @see org.apache.wicket.Component#detachModel()
*/
@Override
protected void detachModel()
{
super.detachModel();
if (title != null)
{
title.detach();
}
if (summary != null)
{
summary.detach();
}
}
@Override
protected void onInitialize()
{
super.onInitialize();
Form<?> form = findParent(Form.class);
form.add(formValidatorWrapper);
}
/**
* Template method that is called when the step is being initialized.
*
* @param wizardModel
* @see #init(IWizardModel)
*/
protected void onInit(final IWizardModel wizardModel)
{
}
/**
* @return wizard model
*/
public IWizardModel getWizardModel()
{
return wizardModel;
}
}