Package org.apache.wicket.markup.html.form

Class Form<T>

    • Method Detail

      • clearInput

        public final void clearInput()
        Clears the input from the form's nested children of type FormComponent. This method is typically called when a form needs to be reset.

      • error

        public final void error​(String error,
                        Map<String,​Object> args)
        Registers an error feedback message for this component
        Parameters:
        error - error message
        args - argument replacement map for ${key} variables

      • findSubmitter

        public final IFormSubmittingComponent findSubmitter()
        THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT!

        Gets the IFormSubmittingComponent which submitted this form.

        Returns:
        The component which submitted this form, or null if the processing was not triggered by a registered IFormSubmittingComponent

      • getDefaultButton

        public final IFormSubmittingComponent getDefaultButton()
        Gets the default IFormSubmittingComponent. If set (not null), a hidden submit component will be rendered right after the form tag, so that when users press enter in a textfield, this submit component's action will be selected. If no default component is set (it is null), nothing additional is rendered.

        WARNING: note that this is a best effort only. Unfortunately having a 'default' button in a form is ill defined in the standards, and of course IE has it's own way of doing things.

        There can be only one default submit component per form hierarchy. So if you want to get the default component on a nested form, it will actually delegate the call to root form.
        Returns:
        The submit component to set as the default IFormSubmittingComponent, or null when you want to 'unset' any previously set default IFormSubmittingComponent

      • getJsForListenerUrl

        public final CharSequence getJsForListenerUrl​(CharSequence url)
        Generate a piece of JavaScript that submits the form to the given URL of an IRequestListener. Warning: This code should only be called in the rendering phase for form components inside the form because it uses the css/javascript id of the form which can be stored in the markup.
        Parameters:
        url - The listener url to be submitted to
        Returns:
        the javascript code that submits the form.

      • getJsForSubmitter

        public final CharSequence getJsForSubmitter​(IFormSubmittingComponent submitter,
                                            boolean triggerEvent)
        Generate a piece of JavaScript that submits the form with the given IFormSubmittingComponent.
        Parameters:
        submitter - the submitter
        triggerEvent - When true, the form will be submitted via standard form submission (requestSubmit()) including client side validation and firing a javascript submit event, when false via the submit() method.
        Returns:
        the javascript code that submits the form.
        See Also:
        findSubmitter()

      • getFileMaxSize

        public Bytes getFileMaxSize()
        Gets maximum size for each file of an upload.
        Returns:

      • getFileCountMax

        public long getFileCountMax()
        Gets maximum count of files in the form
        Returns:

      • getRootForm

        public Form<?> getRootForm()
        Returns the root form or this, if this is the root form.
        Returns:
        root form or this form

      • getValidatorKeyPrefix

        public String getValidatorKeyPrefix()
        Returns the prefix used when building validator keys. This allows a form to use a separate "set" of keys. For example if prefix "short" is returned, validator key short.Required will be tried instead of Required key.

        This can be useful when different designs are used for a form. In a form where error messages are displayed next to their respective form components as opposed to at the top of the form, the ${label} attribute is of little use and only causes redundant information to appear in the message. Forms like these can return the "short" (or any other string) validator prefix and declare key: short.Required=required to override the longer message which is usually declared like this: Required=${label} is a required field

        Returned prefix will be used for all form components. The prefix can also be overridden on form component level by overriding FormComponent.getValidatorKeyPrefix()

        Returns:
        prefix prepended to validator keys

      • hasError

        public final boolean hasError()
        Gets whether the current form has any error registered.
        Returns:
        True if this form has at least one error.

      • isRootForm

        public boolean isRootForm()
        Returns whether the form is a root form, which means that there's no other form in it's parent hierarchy.
        Returns:
        true if form is a root form, false otherwise

      • isSubmitted

        public final boolean isSubmitted()
        Checks if this form has been submitted during the current request
        Returns:
        true if the form has been submitted during this request, false otherwise

      • onMethodMismatch

        protected Form.MethodMismatchResponse onMethodMismatch()
        Called when a form has been submitted using a method differing from return value of getMethod(). For example, someone can copy and paste the action url and invoke the form using a GET instead of the desired POST. This method allows the user to react to this situation.
        Returns:
        response that can either abort or continue the processing of the form

      • onFormSubmitted

        public final void onFormSubmitted​(IFormSubmitter submitter)
        THIS METHOD IS NOT PART OF THE WICKET API. DO NOT ATTEMPT TO OVERRIDE OR CALL IT. Handles form submissions.
        Parameters:
        submitter - listener that will receive form processing events, if null the form will attempt to locate one
        See Also:
        validate()

      • wantSubmitOnNestedFormSubmit

        protected boolean wantSubmitOnNestedFormSubmit()
        Whether this form wants to be submitted too if a nested form is submitted. By default, this is false, so when a nested form is submitted, this form will not be submitted. If this method is overridden to return true, this form will be submitted.
        Returns:
        Whether this form wants to be submitted too if a nested form is submitted.

      • wantSubmitOnParentFormSubmit

        protected boolean wantSubmitOnParentFormSubmit()
        Whether this *nested* form wants to be submitted when parent form is submitted. By default, this is true, so when a parent form is submitted, the nested form is also submitted. If this method is overridden to return false, it will not be validated, processed nor submitted.
        Returns:
        true by default

      • process

        public void process​(IFormSubmitter submittingComponent)
        Process the form. Though you can override this method to provide your own algorithm, it is not recommended to do so.

        See the class documentation for further details on the form processing

        Parameters:
        submittingComponent - component responsible for submitting the form, or null if none (eg the form has been submitted via the enter key or javascript calling form.submit())
        See Also:
        for an easy way to process submitting component in the default manner

      • callOnError

        protected void callOnError​(IFormSubmitter submitter)
        Calls onError on this Form and any enabled and visible nested form, if the respective Form actually has errors.
        Parameters:
        submitter -

      • setDefaultButton

        public final void setDefaultButton​(IFormSubmittingComponent submittingComponent)
        Sets the default IFormSubmittingComponent. If set (not null), a hidden submit component will be rendered right after the form tag, so that when users press enter in a textfield, this submit component's action will be selected. If no default component is set (so unset by calling this method with null), nothing additional is rendered.

        WARNING: note that this is a best effort only. Unfortunately having a 'default' button in a form is ill defined in the standards, and of course IE has it's own way of doing things.

        There can be only one default button per form hierarchy. So if you set default button on a nested form, it will actually delegate the call to root form.
        Parameters:
        submittingComponent - The component to set as the default submitting component, or null when you want to 'unset' any previously set default component

      • setFileMaxSize

        public void setFileMaxSize​(Bytes fileMaxSize)
        Sets maximum size of each file in upload request.
        Parameters:
        fileMaxSize -

      • setFileCountMax

        public void setFileCountMax​(long fileCountMax)
        Sets maximum amount of files in upload request.
        Parameters:
        fileCountMax -

      • setMultiPart

        public void setMultiPart​(boolean multiPart)
        Set to true to use enctype='multipart/form-data', and to process file uploads by default multiPart = false
        Parameters:
        multiPart - whether this form should behave as a multipart form

      • visitFormComponents

        public final <R> R visitFormComponents​(IVisitor<FormComponent<?>,​R> visitor)
        Convenient and typesafe way to visit all the form components on a form.
        Type Parameters:
        R - return object type
        Parameters:
        visitor - The visitor interface to call
        Returns:
        user provided in callback

      • visitFormComponentsPostOrder

        public final <R> R visitFormComponentsPostOrder​(IVisitor<? extends FormComponent<?>,​R> visitor)
        Convenient and typesafe way to visit all the form components on a form postorder (deepest first)
        Type Parameters:
        R - Return object type
        Parameters:
        visitor - The visitor interface to call
        Returns:
        whatever you provided

      • appendDefaultButtonField

        protected void appendDefaultButtonField()
        If a default IFormSubmittingComponent was set on this form, this method will be called to render an extra field with an invisible style so that pressing enter in one of the textfields will do a form submit using this component. This method is overridable as what we do is best effort only, and may not what you want in specific situations. So if you have specific usability concerns, or want to follow another strategy, you may override this method.
        See Also:
        addDefaultSubmitButtonHandler(IHeaderResponse)

      • addDefaultSubmitButtonHandler

        protected void addDefaultSubmitButtonHandler​(IHeaderResponse headerResponse)
        Where appendDefaultButtonField() renders the markup for default submit button handling, this method attaches the event handler to its 'click' event. The 'click' event on the hidden submit button will be dispatched to the selected default submit button. As with appendDefaultButtonField() this method can be overridden when the generated code needs to be adjusted for a specific usecase.
        Parameters:
        headerResponse - The header response.

      • beforeUpdateFormComponentModels

        protected void beforeUpdateFormComponentModels()
        Template method to allow clients to do any processing (like recording the current model so that, in case onSubmit does further validation, the model can be rolled back) before the actual updating of form component models is done.

      • delegateSubmit

        protected void delegateSubmit​(IFormSubmitter submittingComponent)
        Called (by the default implementation of 'process') when all fields validated, the form was updated and it's data was allowed to be persisted. It is meant for delegating further processing to clients.

        This implementation first finds out whether the form processing was triggered by a nested IFormSubmittingComponent of this form. If that is the case, that component's onSubmitBefore/AfterForm methods are called appropriately..

        Regardless of whether a submitting component was found, the form's onSubmit method is called next.

        Parameters:
        submittingComponent - the component that triggered this form processing, or null if the processing was triggered by something else (like a non-Wicket submit button or a javascript execution)

      • getMethod

        protected String getMethod()
        Gets the HTTP submit method that will appear in form markup. If no method is specified in the template, "post" is the default. Note that the markup-declared HTTP method may not correspond to the one actually used to submit the form; in an Ajax submit, for example, JavaScript event handlers may submit the form with a "get" even when the form method is declared as "post." Therefore this method should not be considered a guarantee of the HTTP method used, but a value for the markup only. Override if you have a requirement to alter this behavior.
        Returns:
        the submit method specified in markup.

      • getStatelessHint

        protected boolean getStatelessHint()
        Description copied from class: Component
        Returns whether the component can be stateless. Also the component behaviors must be stateless, otherwise the component will be treat as stateful. In order for page to be stateless (and not to be stored in session), all components (and component behaviors) must be stateless.
        Overrides:
        getStatelessHint in class Component
        Returns:
        whether the component can be stateless
        See Also:
        Component.getStatelessHint()

      • isMultiPart

        public boolean isMultiPart()
        Returns:
        True if is multipart

      • handleMultiPart

        protected boolean handleMultiPart()
        Handles multi-part processing of the submitted data. WARNING If this method is overridden it can break FileUploadFields on this form
        Returns:
        false if form is multipart and upload failed

      • onFileUploadException

        protected void onFileUploadException​(org.apache.commons.fileupload.FileUploadException e,
                                     Map<String,​Object> model)
        The default message may look like ".. may not exceed 10240 Bytes..". Which is ok, but sometimes you may want something like "10KB". By subclassing this method you may replace maxSize in the model or add you own property and use that in your error message.

        Don't forget to call super.onFileUploadException(e, model) at the end of your method.

        Parameters:
        e -
        model -

      • markFormComponentsInvalid

        protected final void markFormComponentsInvalid()
        Mark each form component on this form invalid.

      • markFormComponentsValid

        protected final void markFormComponentsValid()
        Mark each form component on this form and on nested forms valid.

      • encodeUrlInHiddenFields

        protected boolean encodeUrlInHiddenFields()
        Should URL query parameters be encoded in hidden fields, by default true for METHOD_GET only.

        In that case, the parameters must not be written as query parameters, as the browser would strip them from the action url before appending the form values.

        Returns:
        true if form's method is 'get'
        See Also:
        getMethod()

      • writeHiddenFields

        public final void writeHiddenFields()
        Writes the markup for the hidden input fields and default button field if applicable to the current response.

      • onDetach

        protected void onDetach()
        Description copied from class: Component
        Called to allow a component to detach resources after use. Overrides of this method MUST call the super implementation, the most logical place to do this is the last line of the override method.
        Overrides:
        onDetach in class MarkupContainer
        See Also:
        Component.onDetach()

      • onError

        protected void onError()
        Method to override if you want to do something special when an error occurs (other than simply displaying validation errors).

      • onBeforeRender

        protected void onBeforeRender()
        Description copied from class: Component
        Called on all visible components before any component is rendered.

        NOTE: If you override this, you *must* call super.onBeforeRender() within your implementation. Because this method is responsible for cascading Component.onBeforeRender() call to its children it is strongly recommended that super call is made at the end of the override.

        Changes to the component tree can be made only before calling super.onBeforeRender().
        Overrides:
        onBeforeRender in class Component
        See Also:
        MarkupContainer.addOrReplace(Component...)

      • onSubmit

        protected void onSubmit()
        Implemented by subclasses to deal with form submits.

      • updateFormComponentModels

        protected final void updateFormComponentModels()
        Update the model of all components on this form and nested forms using the fields that were sent with the current request. This method only updates models when the Form.validate() is called first that takes care of the conversion for the FormComponents. Normally this method will not be called when a validation error occurs in one of the form components.
        See Also:
        FormComponent.updateModel()

      • validate

        protected final void validate()
        Validates the form by checking required fields, converting raw input and running validators for every form component, and last running global form validators. This method is typically called before updating any models.

        NOTE: in most cases, custom validations on the form can be achieved using an IFormValidator that can be added using addValidator().

      • onValidate

        protected void onValidate()
        Callback during the validation stage of the form

      • onValidateModelObjects

        protected void onValidateModelObjects()
        Called after form components have updated their models. This is a late-stage validation that allows outside frameworks to validate any beans that the form is updating. This validation method is not preferred because at this point any errors will not unroll any changes to the model object, so the model object is in a modified state potentially containing illegal values. However, with external frameworks there may not be an alternate way to validate the model object. A good example of this is a JSR303 Bean Validator validating the model object to check any class-level constraints, in order to check such constraints the model object must contain the values set by the user.

      • validateComponents

        protected final void validateComponents()
        Triggers type conversion on form components

      • getInputNamePrefix

        protected String getInputNamePrefix()
        Allows to customize input names of form components inside this form.
        Returns:
        String that well be used as prefix to form component input names

      • findForm

        public static Form<?> findForm​(Component component)
        Parameters:
        component -
        Returns:
        The parent form for component

      • getRootFormRelativeId

        public static String getRootFormRelativeId​(Component component)
        Utility method to assemble an id to distinct form components from different nesting levels. Useful to generate input names attributes.
        Parameters:
        component -
        Returns:
        form relative identification string