As with any gear page fragment, use the InitializeGearEnvironment tag to initialize your gear environment. For example:

<%@ taglib uri="/paf-taglib" prefix="paf" %>
<paf:InitializeGearEnvironment id="gearEnv">

<%!--CONFIGURATION FORM PAGE CONTENT GOES HERE --%>

</paf:initializeGearEnvironment>

Import your form handler. For example, if you plan to use the GearConfigFormHandler that is provided with the Portal module, you would import it as follows:

<%@ taglib uri="/dsp" prefix="dsp" %>
<dsp:importbean bean="/atg/portal/gear/GearConfigFormHandler"/>

If you need additional functionality in the form handler, you can extend the GearConfigFormHandler class.

Set up the default values needed by your form using <dsp:setvalue> tags to set values in your form handler:

<dsp:setvalue bean="GearConfigFormHandler.paramType" value="instance"/>
<dsp:setvalue bean="GearConfigFormHandler.settingDefaultValues"
              value="false"/>
<dsp:setvalue bean="GearConfigFormHandler.paramNames"
              value="property1 property2 property3"/>

Create your configuration form. The form tag action method differs depending on the type of configuration. For Initial and Instance Configuration, you should use request.getRequestURI(). For User Configuration, use gearEnv.getOriginalRequestURI() to get the URI you want to go to.

For Initial and Instance Configuration, your form tag should look like this:

<dsp:form method="post" action="<%=request.getRequestURI() %>">

<%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%>

</dsp:form>

For User Configuration, your form tag should look like this:

<dsp:form method="post" action="<%=gearEnv.getOriginalRequestURI()%>">

<%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%>

</dsp:form>

Create the hidden fields necessary for navigation and form processing.

The form handler’s successUrl property should be set to the value passed to you in the paf_success_url request parameter by the framework.

<dsp:input type="hidden" bean="GearConfigFormHandler.successUrl"
 value='<%= request.getParameter("paf_success_url") %>'/>

As in every gear page, you must set the following parameters. Note, that the setting of paf_gear_id is necessary in every mode (except in Install Configuration, where only a gear definition exists).

<input type="hidden" name="paf_dm" value="<%=gearEnv.getDisplayMode()%>"/>
<input type="hidden" name="paf_gm" value="<%=gearEnv.getGearMode()%>"/>
<input type="hidden" name="paf_gear_id"
       value="<%=gearEnv.getGear().getId() %>"/>

In Instance Configuration pages, you must also pass through the paf_community_id and paf_page_id parameters for navigation after form processing.

<input type="hidden" param="paf_community_id"
       value="<%=request.getParameter("paf_community_id") %>"/>
<input type="hidden" param="paf_page_id"
       value="<%=request.getParameter("paf_page_id") %>"/>

The GearConfigFormHandler can set user gear parameters and instance gear parameters, and it can set default values or override values. Since you are not creating an Install Configuration page, you are not setting default instance variables, so you would set settingDefaultValues to false and set paramType to instance for all modes except User Configuration, where you would set it to user, as in the following example:

<dsp:input type="hidden" bean="GearConfigFormHandler.settingDefaultValues"
           value="false"/>
<dsp:input type="hidden" bean="GearConfigFormHandler.paramType"
           value="instance|user"/>
<dsp:input type="hidden" bean="GearConfigFormHandler.paramNames"
           value="property1 property2 property3"/>

Create the form’s input fields.

Use dsp:input tags because they need to be processed by the DSP form handler. Get the default values for the form fields from the gearEnvironment, as follows:

<dsp:input type="text" bean="GearConfigFormHandler.values.myParam"
           value='<%= gearEnv.getGearInstanceParameter("myParam") %>'/>

Create the form’s Submit button.

Use a dsp:input Submit button because it will submit to a DSP form handler and it should submit to the handleConfirm method, as in the following example:

<dsp:input type="submit" value="Submit"
           bean="GearConfigFormHandler.confirm"/>

If you have a multipage form you may want to collect values on several pages and submit them all on the last page. GearConfigFormHandler provides a handleCollectValues method to help you do that. Use a button like this for such a multipage form.

<dsp:input type="submit" value="Continue"
           bean="GearConfigFormHandler.collectValues"/>

Add error handling to your form page, as described in the Developing Install Configuration Pages section.