com.atlassian.bitbucket.ui

Interface ContextualFormFragment

public interface ContextualFormFragment

Allows the injection of fields into existing forms provided by the host application.

See Also:

PluginFormFragments

Method Summary

Modifier and Type	Method and Description
void	doError(Appendable appendable, Map<String,String[]> requestParams, Map<String,Collection<String>> fieldErrors, Map<String,Object> context) Render your fields after a validation error has occurred.
void	doView(Appendable appendable, Map<String,Object> context)
void	execute(Map<String,String[]> requestParams, Map<String,Object> context) Store the fields supplied by this form and perform any other actions.
void	validate(Map<String,String[]> requestParams, ValidationErrors errors, Map<String,Object> context) Validate the fields supplied by this form fragment.

Method Detail

doView

void doView(@Nonnull
            Appendable appendable,
            @Nonnull
            Map<String,Object> context)
     throws IOException

Parameters:

appendable - the Appendable to append field HTML that will be injected into the form. The fields should match the style of the pre-existing fields in the form.

context - map with relevant contextual objects

Throws:

IOException - if there was a problem writing to the supplied appendable.

validate

void validate(@Nonnull
              Map<String,String[]> requestParams,
              @Nonnull
              ValidationErrors errors,
              @Nonnull
              Map<String,Object> context)

Validate the fields supplied by this form fragment. This method should not persist any field values, as validation may fail on another field not specified by this ContextualFormFragment. See execute(Map, Map), which is invoked after validate(Map, ValidationErrors, Map) if all fragments have successfully validated. This method should make all reasonable attempts to ensure that the subsequent invocation of execute(Map, Map) will not fail.

Parameters:

requestParams - the map of parameters from the request. This will contain any input supplied by the user in the fields rendered by doView(java.lang.Appendable, java.util.Map<java.lang.String, java.lang.Object>), alongside any other fields in the form rendered by the system or other ContextualFormFragments.

errors - use this to report any validation errors on the input supplied from your fields. See ValidationErrors for more details.

context - map with relevant contextual objects

doError

void doError(@Nonnull
             Appendable appendable,
             @Nonnull
             Map<String,String[]> requestParams,
             @Nonnull
             Map<String,Collection<String>> fieldErrors,
             @Nonnull
             Map<String,Object> context)
      throws IOException

Render your fields after a validation error has occurred. Note that the validation error may have occurred on a field not supplied by this ContextualFormFragment.

Parameters:

requestParams - the map of parameters from the request. This will contain any input supplied by the user in the fields rendered by doView(java.lang.Appendable, java.util.Map<java.lang.String, java.lang.Object>), alongside any other fields in the form rendered by the system or other ContextualFormFragments.

fieldErrors - a Map of String field names to sets of String error messages. If the field name matches one of the fields supplied by your doView(java.lang.Appendable, java.util.Map<java.lang.String, java.lang.Object>) implementation, you should render the error messages alongside your field.

appendable - the Appendable to append field HTML that will be injected into the form, with any relevant errors supplied by the fieldErrors map rendered inline. The fields and error messaging should match the style of the pre-existing fields in the form.

context - map with relevant contextual objects

Throws:

IOException - if there was a problem writing to the supplied appendable.

execute

void execute(@Nonnull
             Map<String,String[]> requestParams,
             @Nonnull
             Map<String,Object> context)

Store the fields supplied by this form and perform any other actions. Any failures at this point are considered unrecoverable and should throw an unchecked exception to halt the request (which will redirect the user to a 500 page). Any recoverable errors should be handled above in the validate(java.util.Map<java.lang.String, java.lang.String[]>, com.atlassian.bitbucket.ui.ValidationErrors, java.util.Map<java.lang.String, java.lang.Object>) method. This method is invoked only if the validate(java.util.Map<java.lang.String, java.lang.String[]>, com.atlassian.bitbucket.ui.ValidationErrors, java.util.Map<java.lang.String, java.lang.Object>) method on all registered ContextualFormFragments and the form's own field validation has completed without any validation errors.

Parameters:

requestParams - the map of parameters from the request. This will contain any input supplied by the user in the fields rendered by doView(java.lang.Appendable, java.util.Map<java.lang.String, java.lang.Object>), alongside any other fields in the form rendered by the system or other ContextualFormFragments.

context - a map of contextual objects that can be used by the form fragment implementation, such as the project, repository or pull request if relevant.