public interface

ContextualFormFragment

com.atlassian.bitbucket.ui.ContextualFormFragment

Class Overview

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

See Also

Summary

Public Methods
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.

Public Methods

public 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. Note that the validation error may have occurred on a field not supplied by this ContextualFormFragment.

Parameters
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.
requestParams the map of parameters from the request. This will contain any input supplied by the user in the fields rendered by doView(Appendable, Map), alongside any other fields in the form rendered by the system or other ContextualFormFragments.
fieldErrors a java.util.Map of String field names to sets of String error messages. If the field name matches one of the fields supplied by your doView(Appendable, Map) implementation, you should render the error messages alongside your field.
context map with relevant contextual objects
Throws
IOException if there was a problem writing to the supplied appendable.

public void doView (Appendable appendable, Map<String, Object> context)

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.

public void execute (Map<String, String[]> requestParams, 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(Map, ValidationErrors, Map) method. This method is invoked only if the validate(Map, ValidationErrors, Map) 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(Appendable, Map), 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.

public void validate (Map<String, String[]> requestParams, ValidationErrors errors, 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(Appendable, Map), 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