[xep-support] Cool Tools: PDF Forms

[Kevin Brown]

Recently, RenderX released version 4.16 which includes support for PDF Forms
as an add-on license. For this installment of "cool tools", I thought I
would introduce this technology and show some sample mark-up. The RenderX
implementation is based on AcroForms technology from the PDF Specification.

PDF Forms requires a license key which enables this functionality. If you
are already a customer of RenderX or just testing things out, you can
request a trial license with PDF Forms enabled at our download page:
http://www.renderx.com/download/index.html

This version of RenderX can create many different types of form fields
including textbox (normal, readonly, password, multi-line), combobox,
selectlist, checkbox, hidden, option groups and various submit, reset
buttons. You can control all the visual elements -- font, border, colors,
backgrounds and attach your own URL to submit buttons. 

The new extension element <pdf-form-field> with it's descendants describes a
single field
in the form. This element and it's descendants exist both in 'rx:' and in
'xep:' namespaces,
so one may define fields in XSL FO documents or in XEP Intermediate Format
documents.

In XSL FO the element <rx:pdf-form-field> is allowed as a direct child of
<fo:inline> or
<fo:block-container> only. When the document is rendered the field is
attached to the first
area produced by it's parent <fo:inline> or <fo:block-container>. So, one
can use these areas to constrain (basically set) the size of the input
field. Since <fo:inline> is supported, it is possible to even insert form
fields directly into a flowing <fo:block>.

Below are a few samples of XSL fragments showing how one can implement form
fields in your documents:

<!-- Implement a textbox field with company name as default text -->
<!-- This textbox has a 1pt solid silver border, italic 8pt font (inherited)
-->
<fo:block-container>
   <rx:pdf-form-field name="textbox2">
       <rx:pdf-form-field-text  border-width="1pt"
        border-style="solid" border-color="silver"
        font-style="italic" font-size="8pt">
            <xsl:attribute name="text">
               <xsl:value-of select="company"/>
            </xsl:attribute>
        </rx:pdf-form-field-text>
    </rx:pdf-form-field>
    <fo:block>
       <fo:leader/>
    </fo:block>
</fo:block-container>

<!-- Implement combobox with the third option default -->
<!-- The combobox has a 1pt solid blue border, a background color wheat
     and all font information inherited -->
<fo:block-container>
   <rx:pdf-form-field name="optionlist1">
      <rx:pdf-form-field-combobox background-color="wheat"
      border-width="1pt" border-style="solid" border-color="blue">
          <rx:pdf-form-field-option text="option1"/>
          <rx:pdf-form-field-option text="option2"/>
          <rx:pdf-form-field-option text="option3"
initially-selected="true"/>
          <rx:pdf-form-field-option text="option4"/>
          <rx:pdf-form-field-option text="option5"/>
          <rx:pdf-form-field-option text="option6"/>
       </rx:pdf-form-field-combobox>
     </rx:pdf-form-field>
     <fo:block>
        <fo:leader/>
     </fo:block>
</fo:block-container>

You can even create "hidden" fields. These are fields that have no visual
appearance so the form recipient cannot change the value nor see it. The
data however IS submitted with the form submittal. Very useful to ensure you
are getting the right information back from users.

<!-- This is a hidden form field carrying the user account number -->
<fo:block-container>
   <rx:pdf-form-field name="account_number" readonly="true" hidden="true">
      <rx:pdf-form-field-text>
         <xsl:attribute name="text">
            <xsl:value-of select="accountnum"/>
         </xsl:attribute>
      </rx:pdf-form-field-text>
   </rx:pdf-form-field>
<fo:block-container>

You can even create submit buttons. A submit button would contain a URL that
points to a server program that can parse the submitted field information.
RenderX currently supports HTML or FDF submit. 

<fo:block-container>
   <rx:pdf-form-field name="Form_Sample">
      <rx:pdf-form-field-submit background-color="#666699"
      border-width="1pt" border-style="solid" border-color="silver"
      color="white"
 
url="http://www.foactive.com/Forms/Service.Handle.PDFFormSubmittal.aspx"
      text="Submit"/>
   </rx:pdf-form-field>
   <fo:block>
      <fo:leader/>
   </fo:block>
</fo:block-container>

This submit button will send FDF form information to our FDF parser for
further handling. Feel free to use our URL if you wish, it will just display
the results of your form submittal.

There are a few things to know about forms and how they work to ensure you
set up your environment correctly. First, all fields must have a unique
"name" attribute. If you happen to name two fields the same name, the second
occurrence will be omitted from the output.

Second, because forms allow the end user to input data, you need to ensure
that fonts they will use are embedded and NOT subsetted. it is always safest
to use the base 14 fonts if possible if the end user is not entering
characters outside what these fonts contain. If you have international forms
needs and need to use a font like Arial Truetype, then you *must* embed and
not subset the font. The whole font must be avaiable for the end user to
type characters. Please note that this can increase the font size
considerably, so design well. If you create a form requiring Arial and its
variants (Bold, Italic, Bold-Italic), this would increase the size of the
PDF by 1.6MB. Forms also require that the fonts initial-encoding be set to
standard. A default install of XEP as of 4.15 has all the proper settings in
xep.xml to produce forms for the base 14 fonts, you do not need to make any
modifications unless you copy over this xep.xml with an older version.

RenderX has created a sample we can make available that has most all of the
form elements implemented in a sample FO. Just contact me and i would be
happy to send it along to you.

If you have any questions, feel free to contact us and we would be happy to
help you get started producing dynamic, interactive forms for your
customers.

Kevin Brown
RenderX
kevin at renderx.com
(650) 327-1000

-------------------
(*) To unsubscribe, send a message with words 'unsubscribe xep-support'
in the body of the message to majordomo at renderx.com from the address
you are subscribed from.
(*) By using the Service, you expressly agree to these Terms of Service http://www.renderx.com/terms-of-service.html