Displaying forms

This recipe explains how to display forms on your Viewport.

For information on how to create a form, see Create Forms.

Overrides for Form and Form Elements

The method for overriding a form macro in Viewport is the same one as overriding any other macro. Check the Macros Overrides section in the Advance Content Rendering guide for more information.

Overriding the Form Container Macro

Create a sp-form.vm file in your overrides folder.

overrides/sp-form.vm

XML

<form action="$contextPath/plugins/servlet/scroll-viewport/form-submit" name="$formName" method="POST" enctype="application/x-www-form-urlencoded">
    <input type="hidden" name="viewportId" value="$viewportId"/>
    <input type="hidden" name="pageId" value="$pageId"/>
    <input type="hidden" name="formPageId" value="$formPageId"/>
    <input type="hidden" name="formName" value="$formName"/>
    <input type="hidden" name="formHandler" value="$formHandler"/>
    
   #if ($submitResult.status && $submitResult.status.statusCode == 200)
       ## this is displayed, if the form submit was successful....
       <p class="sp-message sp-message-success">$submitResult.message</p>
   #else
      #if($submitResult.status && $submitResult.status.statusCode != 200)
        ## this is displayed, when the form submit failed....
        <p class="sp-message sp-message-error">$submitResult.message</p>
      #end
      $body
      <div class="buttons">
        <input class="button submit" type="submit" name="submit" value="Save" id="d-save-btn1">
        <a class="cancel" href="#">Cancel</a>
      </div>
    #end
</form>

Fields / Methods for the Form Container Macro

Name	Type	Description
`$formName`	String	Return the name of the form.
`$formHandler`	String	Return the form's handler
`$submitResult.success`	Boolean	Returns `true` if form submitting worked.
^{$submitResult.message}	String	Returns the success message.

Fields / Methods for the Form Elements Macros

Placeholder allow you to get the values from the macro's parameters.

Name	Type	Description
`$field.name`	String	Returns the name specified by the user.
`$field.required`	boolean	Returns `true` if the user specified that the field is required.
`$field.options`	List	Returns a list with the values entered values.
`$field.description`	String	Returns the description entered by the user.
^$field.size	String	Returns the size specified by the user.
^$field.label	String	Returns the label predefined by the user.
^{$field.defaultValue}	String	Returns the default value of the field, defined by the user.
^$presetValue	String	Returns the field value when form validation failed
^{$validationError}	String	Returns the error message, when form validation fails

Here is an example of the input field including every method. Please note that when writing an override, all the form properties should be taken into account.

input.vm

XML

 <div class="field-group sp-fieldname-${field.name}">
    
	<label for="form-input-${field.name}">$field.label
        #if($field.required)
            <span class="aui-icon icon-required"> required</span>
        #end
    </label>

    <input class="text" type="text" id="form-input-${field.name}" name="$field.name" title="$field.label" 
		#if($!presetValue) 
			value="$presetValue" 
		#elseif ($!field.defaultValue) 
			value="$field.defaultValue" 
		#end
	>
    
	#if ($field.description)
        <div class="description">$field.description</div>
    #end
    
	#if ($validationError)
        <div class="error">$validationError</div>
    #end
</div>