PDF Forms

From Scribus Documentation Project

Jump to: navigation, search

Contents

PDF Forms

Introducing PDF Form Elements

Scribus has the ability to create PDF forms with embedded JavaScript scripts. PDF forms are in some cases filled out by users on their computers and then printed out locally, but information in a PDF form may also be submitted online to a remote location for further processing. However, this online submission only works with Adobe Reader 8 or later; in earlier versions of Adobe Reader, the feature is only available if you are using the Adobe Reader plug-in for your browser, not with the standalone Reader application.

Start With OK

On your toolbar, find the icon with the default “OK” label, which by the way changes as you select from the list. Attached to its right side is an expander to generate a drop-down list of choices: Button, Text Field, Check Box, Combo Box, and List Box. By selecting one of these, you can then go to your document and click-drag to create a frame, which you will perhaps be disappointed to see merely creates a generic-appearing empty text frame.

What this shows is that simply making one of these form items does not do much of anything – each needs content, associated attributes, and actions to be useful in your PDF form.

Button

A Button has several operations it can carry out. It might show itself as a text message, but you can also load an image for the button, and create your own tooltip. When clicked, you could go to a particular page of the same or a different PDF, submit data from the form, reset the form, run a short JavaScript command, or import some data to the form.

Text Field

A Text Field, not surprisingly, is for entering some keyboard input to submit with the form. You can set limits as to its length, perform some sort of testing of the input, make some calculation based on the input, and again, perform some action with JavaScript.

Check Box

Clicking on this will, in the PDF Form, make or unmake a checkmark of some sort, the type chosen from a list in Scribus. Some JavaScript action can be carried out here also – see the Emulating Radio Buttons for one such use of JavaScript.

Combo Box

For a Combo Box, create a list in the frame Scribus (with Story Editor for example), this simply being a column of possible choices, which can be editable or not. Any blank lines will not appear in the PDF Form, and even if your frame height is much larger than the line spacing, only one choice appears at a time, until you click the right side feature to expand the list in a drop-down manner.

List Box

Like the Combo Box, a List Box is a simple text list of items. There is no drop-down feature like a Combo Box, but instead use these scrolling arrows as seen here – you need to click the box to bring the scrolling feature in view. In contrast to the Combo Box, a List Box will show as many choices as can be visible for the frame height chosen, with the actual choice to be submitted being highlighted.

PDF Form Features in Scribus

What we want to do in this chapter is to go through the process of creating a relatively simple PDF form with Scribus, incorporating at least the basic elements than can be used. Since there are many options, we will not plan to cover all of them, but some aspects of forms, such as JavaScript will be covered in later sections.

A Demonstration Form

Let's envision that we want to do a brief survey by collecting some basic biographical information, then some various opinions and other kinds of information.

We'll plan on collecting this information:

  • The person's name
  • Address
  • City, Country
  • Then ask them to make a series of choices

Text Field

Here is the beginning of our form. The frames outlined in black containing text are regular text frames. The others are special text frames called “Text Fields”, obtained by selecting text field from the drop-down list in the menu bar. PDF form elements will not be found in the menus.


For visual simplicity, we have kept the background plain, but depending on your preference, you might choose to use a grid or guides to assist with placement and alignment of these frames. A text field will be used to allow for filling out the space freely from the keyboard, rather than supplying choices.

When we right-click on each of these text fields, then choose “PDF Options > Field Properties” from the context menu, this dialog comes up. Instead of Text1, we will want to enter the variable name for each piece of data, so for our form, the text fields will have the variable names Name, Address, City, and Country.


In our example, we will keep things simple, but for our “Name” category we might, for example, type “First, (MI), Last” as a tooltip so those filling out the form know our preferred entry order.

In contrast to regular text frames, we have limited choices for various features of our form fields. If we export to PDF version 1.3, for our font we can only choose regular, bold and italic forms of Courier, Helvetica, and Times, plus Symbols and Zapf Dingbats. The color of the border has a full range of choices, but the thickness can only be “None”, “Thin”, “Normal”, and “Wide”. Choices in Style are “Solid”, “Dashed”, “Underline”, “Beveled”, and “Inset”.

In our Options tab, we have these checkbox choices, but for our example we will leave all unchecked. “Do Not Scroll” and “Do Not Spellcheck” will have no effect with PDF 1.3.


The Action tab only gives us a choice of “None” or “Javascript”, so this will not be shown further here.


For our example we will leave the format as “Plain” (as in plain text). Other choices are:

  • “Number,” for which you can select number of decimal places, the character to use to indicate the decimal separator (period or comma), and whether to add a currency symbol.
  • “Percentage,” where again we can choose the number of decimal places and the character to show the decimal separator.
  • “Date” – various date formats possible.
  • “Time” – again various format choices are shown.
  • “Custom,” where one must enter some personalized way of making a format for the entry.

In the Validate tab, we have a number of ways to check the entry into our text field. For our example, we will not make any changes.


Finally, in the Calculate tab, we can change the settings to cause this field to be the sum, product, average, minimum, or maximum of a set of other fields in our form. We can also have a custom method of calculation. For our example, we will choose “Value” is not calculated.

Check Box

Checkboxes are a relatively simple element, with only a few options. You must manually size your box, and you can choose between the choices you see here:

Enlarge the size of your mark with the font size spinbox in Properties > Text tab. Since you will not see this mark in Scribus, some experimentation will be necessary to balance the size of the check with the size of the box. The default can be either to have the box checked or unchecked. Each of these will of course have an associated text frame for the corresponding choice, and you must also align the text frame manually with the checkbox.

The Action tab for checkboxes also allows triggering of some JavaScript operation.

Combo Box and List Box

In many ways a Combo Box is similar to a List Box, so these will be described together here. Each allows you to choose an item from a list of choices, although the way these are displayed is somewhat different. A Combo Box will show only one choice regardless of its height as the default. In contrast, a List Box will show as many as can be seen for the height of the frame.

Unlike the PDF Fields mentioned thus far, you will see the contents of these boxes in Scribus. Create them to the desired height and width, then use Story Editor to make the list of choices, each on a separate line. After saving and closing Story Editor, now bring up the PDF Options > Field Properties dialog as we have before.

Here we see how the Combo Box appears in Adobe Reader after clicking the drop-down button. It may make more sense to use a Combo Box when the list of choices is long and especially when very different from one another, or for some other reason you want to be able to see all at once.


Here then is the List Box sized to only choice show one at a time. List Boxes can make more sense when the various choices occur in some natural order.


If you look at the Options tab in Field Properties, it would appear that you can allow entries in a Combo Box and a List Box to be editable, but you will find that only Combo Boxes can be edited in Adobe Reader. This may also be a reason to choose one over the other. Image:Combobox_editable.png

Button

Although Button is the top choice in the Insert PDF Fields list, we're mentioning it last, since in many cases it will be something you click on after you have filled in or selected choices in other form elements.

Let's focus on a particular type of button, a submit button. Here we see this as one of the choices in the Action tab:


You can have your button say anything you like, but usually something simple works best.

When you select Submit Form, you then need to enter the URL where your data will be sent. On the receiving end, you must have some way, such as a PHP file, to accept the information from the form.

If your system is set up properly, you can alternatively enter mailto:, then an email address for sending the information from the form.

In some cases, as shown here, you will want to check submit data as HTML. If you do not check this, the data will be sent in Adobe's FDF format. When submitting to a URL, your PHP file will need to be able to handle the appropriate data format. In either case, Adobe Reader must allow transmission of data, and the receiving site must allow for reception of this information.

Other Options

One thing you will not be able to do with a PDF form generated by Scribus is to save the data directly from Adobe Reader. You can, however, simply print the completed form on a local printer.

Enhancing PDF Forms With JavaScript

Now that you have learned the basics of PDF forms in Scribus, you will probably be looking for more advanced features to customize your forms. One of the best ways to do so is by using JavaScript. JavaScript in PDF forms enables you to manipulate the appearance of form elements or even of the whole document, and to calculate and validate the contents of PDF form elements by attaching JavaScript code to events of its text fields, buttons, or even of the form itself.

As it is outside of the scope of the Scribus manual to cover all PDF-related JavaScript features, you are advised to download the JavaScript for Acrobat API Reference for a comprehensive list of available objects, methods and properties. [1]

Adding New Functions

Go to Edit > Javascripts … and click on “Add.” Choose a name for your new function and click on “OK” to launch the built-in JavaScript editor.

Let us call our first function “RunOnLaunch” and start with a simple alert that will be displayed on launching the PDF form in Adobe Reader:

function RunOnLaunch() {
  app.alert('Welcome to the Scribus Demo Form!');
}

Launching JavaScript Functions While Opening Documents

Go to File > Export > Save as PDF and click on the “Viewer” tab. Choose the JavaScript to be executed from the “Special Actions” dropdown list. Save the PDF document and open it in Adobe Reader to see how it works.

Adding JavaScript Actions to Form Field Events

Let us make some text fields and text frames first. We will also need an optional check box and a button for performing some JavaScript actions (see the picture below).

Validate Form Fields

First, we want to prevent users from submitting empty form fields. Right click on the button, choose “PDF Options > Field properties” from the context menu, go to the “Action” tab, choose “JavaScript” from the “Type” dropdown list and add the following snippet of JavaScript code to the “MouseDown” event:

if(!this.getField('field1').value) {
    app.alert('Please fill a number into field 1');
 } else if (!this.getField('field2').value) { 
    app.alert('Please fill a number into field 2');
 }

Calculate Form Field Values

Now we would like to perform some simple calculations on form field values. In the following example, we will sum up the values of “field1” and “field2” and increase the result by 20%, depending on whether “checkbox1” has been checked or not. The final result will be displayed in the third form field. The code snippet below has to be pasted into the “MouseDown” event of the red button too.

 if(!this.getField('field1').value) {
    app.alert('Please fill a number into field 1');
 } else if (!this.getField('field2').value) { 
    app.alert('Please fill a number into field 2');
 } else {
    app.alert('Adding field1 to field2 and putting the result into field3');
    this.getField('field3').value = this.getField('field1').value + this.getField('field2').value;
    app.alert('and now add 20% VAT to the result, if checkbox1 is checked ');
    var v = this.getField('checkbox1');
    if(v.value=='Yes')
        var vat = this.getField('field3').value * 0.2;
    else
        var vat = 0;
    this.getField('field3').value = this.getField('field3').value + vat;
 }

Changing Field Properties With a Document Wide Script Executed on Button Click

First, let’s create one combo box, one list box, a text field and a button. Use the PDF Tools icons to achieve this.

To add list items to a combo box or a list box, right-click on it and select “Edit Text …” from the context menu. Add one line of text for each list item and close the Story Editor.

The next step is to write a new JavaScript function. Go to Edit > Javascripts …, click on “Add,” choose a name for your new function, eg. “SetFieldValues,” and add the following snippet of JavaScript code to it. The code is meant to be self-explanatory, see the comments inside the function.

function SetFieldValues()
 {
  app.alert('Running a document wide script SetFieldValues. To see how it works, open the  source document in Scribus and go to  Edit/JavaScripts.');
  app.alert('Changing the values of the combobox and the listbox');
  //setting combobox value to 12
  this.getField("combobox1").value = '12';
  //setting listbox value to option 3
  this.getField("listbox1").value = 'option 3';
  // Get the current date and time
  var rightNow = new Date();
  rightNow     = rightNow.toLocaleDateString();
  var fld = this.getField("date");
  //Change the date field border to dark blue
  app.alert('Changing the date field border to dark blue, setting the date to current value, and changing the date text color to purple.');
  fld.strokeColor = ["RGB",0.5,0.5,1];
  //Change fill to light blue, won't work for unknown reason
  fld.Color = ["RGB",0,0,0.7];
  //set the value of the date field to current date
  fld.value     = rightNow;
  //Change text of the date field to purple
  fld.textColor = ["RGB", 0.5, 0, 0.5];

The function we have just written is now there, but it has to be tied to a PDF form element to make it really work. Right-click on the button, choose “PDF Options > Field Properties” from the context menu, go to the “Action” tab, choose “JavaScript” from the “Type” dropdown list and add the following line to the “MouseDown” event:

[1] http://partners.adobe.com/public/developer/en/acrobat/sdk/pdf/javascript/AcroJS.pdf

Emulating Radio Buttons

The screenshots from http://wiki.scribus.net/index.php/How_to_simulate_Radio_Buttons_on_PDF_forms need to be redone in PNG format.

Currently, Scribus cannot create real radio buttons in PDF forms, because the PDF specification for creating radio button objects requires a group of items with an identical name. Scribus does not support objects with an identical name. Fortunately, a group of check boxes, each containing a little JavaScript, can be used to simulate a group of radio buttons.

The Method by Example

Select “Check Box” from the “PDF Fields” dropdown list in the toolbar:

In your document, create two or more check boxes and use a text frame to label each with suitable text. Each check box should also have a suitable name to reflect the purpose.

In our example we will have three check boxes called “Yes,” “No,” “Maybe” and three text frames containing “YES,” “NO,” “MAYBE.” Be careful with the names when you are using JavaScript as Adobe Reader is case sensitive. You should end up with something like this on your page:

Right-click with your mouse on the “Yes” Checkbox (blue square). From the context menu select “PDF Options > Field Properties.” In the dialog, go to “Action Tab” and choose “JavaScript,” then use the default “Mouse Up” event. Click on the “Edit” button and type the following code:

//this.getField("Yes").value = "Off" 
this.getField("No").value = "Off" 
this.getField("Maybe").value = "Off"

The initial “//” means that the first line will not be executed as a command, as it is not required for this field. Doing it this way makes it easy to copy and paste the complete code to all the check boxes and reduces typing errors. Click on “Save” and “Exit.” The dialog should now look like this:

For the “No” check box, repeat the process with:

this.getField("Yes").value = "Off"
//this.getField("No").value = "Off" 
this.getField("Maybe").value = "Off"

and then with the “Maybe” check box:

this.getField("Yes").value = "Off" 
this.getField("No").value = "Off" 
//this.getField("Maybe").value = "Off"

Save your Scribus document as a PDF file and view the PDF file using Adobe Reader. Now you should see the following fields that work like radio buttons:

If you want to use traditional “round” radio button, you need to create an illusion.

For your check boxes use the following settings:

“Appearance” tab:

  • Color: None
  • Width: None
  • Style: Solid

“Options” tab:

  • Check Style: Circle

Now use the Scribus “Shape” tool to draw a circle around the check box. The resulting PDF should look like this:

Annotations and Links in PDF Files

Creating a PDF Annotation

PDF annotations can be useful for many purposes, and their advantages aren’t limited to PDF forms. For instance, it’s possible to send a PDF proof to customers and add annotations to get some feedback or to tell them you need a different file.

Here is a summary of what we need to do:

  • Create a text frame, enter text
  • Check context menu > PDF Options > Is PDF Annotation
  • Context menu, open Annotation Properties
  • Select “Text” from dropdown list

To create a PDF annotation, create a text frame where you want the annotation to be displayed. Open the Story Editor and type your text. Note that you can’t choose any text formatting for annotations.

In our example we want to tell someone that we need an image at a higher resolution:

After typing the text, close the Story Editor. Don’t be scared when you see unreadable text above the image. Annotations won’t be visible in a PDF viewer, and they won’t print either:

Next, open the context menu and check PDF Options > Is PDF Annotation:

Open the context menu again and click PDF Options > Annotation Properties:

Choose “Text” from the dropdown list:

Now export your document as a PDF file and open it in Adobe Reader. There you see that the annotation is indicated by a page symbol. If you hover your mouse over the icon, the annotation is displayed:

Internal Links

Another feature of PDF annotations is their use as links, like you are used to from web pages. You can create links within a document, links to external PDF files or hyperlinks.

To create a link within a document, select “Link” from the dropdown list in the Annotation Properties. Under “Destination” you can choose the page to which you want to link to. Scribus will display a preview of the selected page, so that you can easily select a destination with the mouse. If you need more precision, you can set the X and Y coordinates.

External Links

If you are using Scribus for presentations, it can be useful to link to another PDF file which could be opened in the same viewing application. Choose “External Link” from the dropdown list. Scribus will now open a file dialog from which you can choose the file. Once you have selected a PDF file, Scribus opens the “Annotation Properties,” where you can choose the page to link to as well as the X and Y coordinates on the page:


Note that Scribus saves absolute paths to external files.

External Web Links

If you select “External Web Link,” Scribus lets you insert a hyperlink. In most cases you will enter a web adress, like www.scribus.net, but you can also enter an email address. Just like in HTML pages you have to insert “mailto:” before the email address, eg. mailto:person@address.net. If properly configured, your email program will be opened through your browser.

Some Additional Notes

  • Regardless of the size of your annotation frame, the clickable area for the text type will be a small area near the page icon.
  • In contrast, for a link, external link, or external weblink the clickable area is determined by the size of your frame – you will see the pointing hand icon appear.
  • Consider these as special text frames, since any text frame can become an annotation or link. The text content becomes your annotation for text type. For links, any text is invisible. For all types, any background or line color is invisible.
  • You can, of course, convert an image, shape, or polygon frame to a text frame, then to an annotation. The image will disappear in Scribus and in the PDF. For shapes and polygons Scribus will continue to show the shape and its associated colors. When you export to PDF, however, the colors disappear, and the clickable area is the rectangular bounding box, not just the shape or polygon.

PDF Viewers for Forms

The best viewer for PDF forms is Adobe Reader, as it fully supports the whole PDF forms feature set. Moreover, Firefox can display forms with the Reader’s “nppdf” plug-in. Okular in KDE 4 will support PDF forms as well.

CABAReT Stage [1] is proprietary, but freely available for personal use, and it has both Windows and Linux versions. It can have some problems (at least in Linux) with fonts, and perhaps some other factors for proper filling out of forms. The free versions have abilities for editing PDF forms, but will introduce a rather ugly “watermark” in the background while doing so – one must purchase a version to prevent this. However, the most important feature of the gratis version of CABAReT Stage is its ability to save the content inserted into PDF forms.

Linux users should be aware of the fact that CABAReT Stage may not work at all or even freeze your desktop (as experienced on OpenSUSE 10.3). As a workaround, you can open a PDF form in Adobe Reader, fill it out and print to a PostScript file. Then open the PS file in GSview and convert it to PDF. KDE users can also insert kprinter as an alternative printing command in Adobe Reader’s print dialog and export directly to PDF.

[1] http://www.cabaret-solutions.com

Personal tools