info.magnolia.module.form.engine
Class FormEngine

java.lang.Object
  info.magnolia.module.form.engine.FormEngine

Direct Known Subclasses:

AbstractFormEngine

public abstract class FormEngine
extends Object

Implements a rendering and form submission algorithm that keeps state in session for multiple pages. Subclasses implement extension hooks to provide the actual views used.

Field Summary

info.magnolia.rendering.context.RenderingContext	context
protected boolean	redirectWithParams

Constructor Summary

FormEngine(info.magnolia.rendering.context.RenderingContext context)

Method Summary

protected FormState	createAndSetFormState()
protected void	destroyFormState()
protected abstract void	executeProcessors(Map<String,Object> parameters)
protected abstract FormDataBinder	getFormDataBinder()
FormState	getFormState()
protected FormState	getFormState(String formStateToken)
protected String	getFormStateToken()
protected abstract View	getFormView(FormStepState step) Called when the form is to be rendered.
protected String	getNextPage() Returns the UUID of the page to redirect to when validation succeeds or null to proceed to executing processors.
protected String	getPreviousPage() Returns the UUID of the previous page or null if there is no such page (i.e.
protected abstract View	getProcessorFailedView(String errorMessage) Called when a processor failed.
protected abstract View	getSuccessView() Called when validation was successful and all processors executed successfully.
protected View	getValidationFailedView(FormStepState step) Called when validation fails.
protected View	getValidationSuccessfulView(FormState formState) Called when validation has been performed and there were no validation errors.
protected abstract View	handleNoSuchFormState(String formStateToken) Called when the form was to be rendered for a supplied form token but there is no state in the session.
protected View	handleNoSuchFormStateOnSubmit(String formStateToken) Called when a submission occurs with a form state token but there is no formState in session.
View	handleRequest(javax.jcr.Node content)
protected View	handleTokenMissing() Called when the form is to be rendered and there's no token provided.
protected boolean	isBackButton()
protected boolean	isFormSubmission()
boolean	isRedirectWithParams()
void	setFormState(FormState formState)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

redirectWithParams

protected boolean redirectWithParams

context

public info.magnolia.rendering.context.RenderingContext context

Constructor Detail

FormEngine

@Inject
public FormEngine(info.magnolia.rendering.context.RenderingContext context)

Method Detail

handleRequest

public View handleRequest(javax.jcr.Node content)
                   throws javax.jcr.RepositoryException

Throws:

javax.jcr.RepositoryException

isRedirectWithParams

public boolean isRedirectWithParams()

createAndSetFormState

protected FormState createAndSetFormState()

getFormStateToken

protected String getFormStateToken()
                            throws FormStateTokenMissingException

Throws:

FormStateTokenMissingException

getFormState

protected FormState getFormState(String formStateToken)
                          throws NoSuchFormStateException

Throws:

NoSuchFormStateException

destroyFormState

protected void destroyFormState()

getFormState

public FormState getFormState()

setFormState

public void setFormState(FormState formState)

isFormSubmission

protected boolean isFormSubmission()

isBackButton

protected boolean isBackButton()

Returns:

true if the user hit the back button in the form. This relies on the presence of a request param called mgnlFormBackButtonPressed. Check formSubmit.ftl script to see how it works on the client-side.

handleTokenMissing

protected View handleTokenMissing()
                           throws javax.jcr.RepositoryException

Called when the form is to be rendered and there's no token provided. The default behaviour is to return a view that renders the form without creating a new form state.

Throws:

javax.jcr.RepositoryException

getFormView

protected abstract View getFormView(FormStepState step)
                             throws javax.jcr.RepositoryException

Called when the form is to be rendered.

Parameters:

step - is null when we render the page for the first time. I.e. when no validation has taken place.

Throws:

javax.jcr.RepositoryException

getValidationSuccessfulView

protected View getValidationSuccessfulView(FormState formState)
                                    throws javax.jcr.RepositoryException

Called when validation has been performed and there were no validation errors. Override this method to add multi step support.

Throws:

javax.jcr.RepositoryException

getNextPage

protected String getNextPage()
                      throws javax.jcr.RepositoryException

Returns the UUID of the page to redirect to when validation succeeds or null to proceed to executing processors.

Throws:

javax.jcr.RepositoryException

getValidationFailedView

protected View getValidationFailedView(FormStepState step)
                                throws javax.jcr.RepositoryException

Called when validation fails.

Throws:

javax.jcr.RepositoryException

getProcessorFailedView

protected abstract View getProcessorFailedView(String errorMessage)
                                        throws javax.jcr.RepositoryException

Called when a processor failed.

Parameters:

errorMessage - can be null in case another exception than FormProcessorFailedException is thrown by processor.

Throws:

javax.jcr.RepositoryException

getSuccessView

protected abstract View getSuccessView()
                                throws javax.jcr.RepositoryException

Called when validation was successful and all processors executed successfully.

Throws:

javax.jcr.RepositoryException

handleNoSuchFormState

protected abstract View handleNoSuchFormState(String formStateToken)
                                       throws javax.jcr.RepositoryException

Called when the form was to be rendered for a supplied form token but there is no state in the session. This typically happens when the user navigates back after having completed the form or if the user returns later via a bookmark or via browser history.

Throws:

javax.jcr.RepositoryException

handleNoSuchFormStateOnSubmit

protected View handleNoSuchFormStateOnSubmit(String formStateToken)
                                      throws javax.jcr.RepositoryException

Called when a submission occurs with a form state token but there is no formState in session. This typically happens when the user has waited so long to complete the form that the session timed out.

Throws:

javax.jcr.RepositoryException

getFormDataBinder

protected abstract FormDataBinder getFormDataBinder()

executeProcessors

protected abstract void executeProcessors(Map<String,Object> parameters)
                                   throws javax.jcr.RepositoryException,
                                          FormProcessorFailedException

Throws:

javax.jcr.RepositoryException

FormProcessorFailedException

getPreviousPage

protected String getPreviousPage()

Returns the UUID of the previous page or null if there is no such page (i.e. there's one or no steps in current form state).