Using predefined forms in a html design

The look of a form in your definition can be changed by a stylesheet. However you may also want to show the form inside a html design or page. There are several ways of doing this.

Before going on, you should realize that a form is not just one screen with some fields and a submit button. Actually it may involve entering data in several steps on seperate pages. Also possibly validation messages or pages may show up. Finally, when data has been submitted, a succeeded or failed page may be shown.

Using a surrounding page

By default, a form will be shown in the surrounding page that is applicable for the current user viewing the form. Often this is fine but you may want a different surrounding page for the form. In these case you can use the surrounding page field of the form definition.

Form embedding using velocity

You can also embed your form using velocity. Using this method it is possible to reuse the same form in different designs, something which is more difficult to do using the surrounding page method as described above. You just need to know the number of the form definition and use the following code.

$session.getFormHTML('D1')

This single line of code will embed a predefined form (in this case D1) on any page. The entire handling of the form will be shown inside the page where this line of code was first evaluated. So you could create a velocity file like this:

$document.surround()
<h2>This is my form</h2>
<img src="myFormImage.jpg">
<p>Here is some text.... </p>
$session.getFormHTML('D1')

And another one like this:

$document.surround()
<h2>This is the same form</h2>
<img src="differentImage.jpg">
<p>Different text.... </p>
$session.getFormHTML('D1')

This method is also very convenient if your application uses a CMS like system and you want users to be able to stick a form on any page they created. Let's imagine you have created a class called "webpage with form". The page has a title, some content and a field in which the user can select a form. Now a simple veloctiy template renders the page on the web.

$document.surround()

<h2>$record.getLabel('Title')</h2>
$record.getLabel('Content')

#if($record.get('Form'))
    $session.getFormHTML($record.get('Form'))
#end

Example screenshots of a embedded form using velocity

Surrounding page only • The surrounding page including content form the CMS rendered by a velocity template • Final page

Using the "surround" query string parameter

It is also possible to use a different surrounding page for a form using the "surround" query string parameter. A normal request for a form would look like this:

/engine?service=classmanager:form:1&cmd=new

Now add any url to the request as the query string parameter value like this:

/engine?service=classmanager:form:1&cmd=new&surround=/test.vm

The form will have the same surrounding page as long as the user's session exists or until it is changed by a different "surround" parameter value. It is also possible to reset the surrounding page of the form to it's original, by including the "surround" parameter in the request without a value.