php-doc-en/functions/fdf.xml
2002-01-07 02:52:21 +00:00

629 lines
20 KiB
XML

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
<reference id="ref.fdf">
<title>Forms Data Format functions</title>
<titleabbrev>FDF</titleabbrev>
<partintro>
<simpara>
Forms Data Format (FDF) is a format for handling
forms within PDF documents. You should read the documentation at
<ulink url="&spec.pdf.fdf;">&spec.pdf.fdf;</ulink>
for more information on what FDF is and how it is used in general.
</simpara>
<note><simpara>
If you run into problems configuring php with fdftk support, check
whether the header file FdfTk.h and the library libFdfTk.so are at
the right place. They should be in fdftk-dir/include and
fdftk-dir/lib. This will not be the case if you just unpack
the FdfTk distribution.
</simpara></note>
<simpara>
The general idea of FDF is similar to HTML forms. The difference is
basically the format how data is transmitted to the server when the submit
button is pressed (this is actually the Form Data Format) and the format
of the form itself (which is the Portable Document Format, PDF).
Processing the FDF data is one of the features provided by the fdf
functions. But there is more. One may as well take an existing PDF form
and populated the input fields with data without modifying the form
itself. In such a case one would create a FDF document
(<function>fdf_create</function>) set the values of each input field
(<function>fdf_set_value</function>) and associate it with a PDF form
(<function>fdf_set_file</function>). Finally it has to be sent to the
browser with MimeType <literal>application/vnd.fdf</literal>. The Acrobat
reader plugin of your browser recognizes the MimeType, reads the
associated PDF form and fills in the data from the FDF document.
</simpara>
<simpara>
If you look at an FDF-document with a text editor you will find a
catalogue object with the name <literal>FDF</literal>. Such an object may
contain a number of entries like <literal>Fields</literal>,
<literal>F</literal>, <literal>Status</literal> etc..
The most commonly used entries are <literal>Fields</literal> which points
to a list of input fields, and <literal>F</literal> which contains the
filename of the PDF-document this data belongs to. Those entries are
referred to in the FDF documention as /F-Key or /Status-Key.
Modifying this entries
is done by functions like <function>fdf_set_file</function> and
<function>fdf_set_status</function>. Fields are modified with
<function>fdf_set_value</function>, <function>fdf_set_opt</function> etc..
</simpara>
<simpara>
The following examples shows just the evaluation of form data.</simpara>
<simpara></simpara>
<example>
<title>Evaluating a FDF document</title>
<programlisting>
<![CDATA[
<?php
// Save the FDF data into a temp file
$fdffp = fopen("test.fdf", "w");
fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
fclose($fdffp);
// Open temp file and evaluate data
// The pdf form contained several input text fields with the names
// volume, date, comment, publisher, preparer, and two checkboxes
// show_publisher and show_preparer.
$fdf = fdf_open("test.fdf");
$volume = fdf_get_value($fdf, "volume");
echo "The volume field has the value '<B>$volume</B>'<BR>";
$date = fdf_get_value($fdf, "date");
echo "The date field has the value '<B>$date</B>'<BR>";
$comment = fdf_get_value($fdf, "comment");
echo "The comment field has the value '<B>$comment</B>'<BR>";
if(fdf_get_value($fdf, "show_publisher") == "On") {
$publisher = fdf_get_value($fdf, "publisher");
echo "The publisher field has the value '<B>$publisher</B>'<BR>";
} else
echo "Publisher shall not be shown.<BR>";
if(fdf_get_value($fdf, "show_preparer") == "On") {
$preparer = fdf_get_value($fdf, "preparer");
echo "The preparer field has the value '<B>$preparer</B>'<BR>";
} else
echo "Preparer shall not be shown.<BR>";
fdf_close($fdf);
?>
]]>
</programlisting>
</example>
</partintro>
<refentry id="function.fdf-open">
<refnamediv>
<refname>fdf_open</refname>
<refpurpose>Open a FDF document</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>fdf_open</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_open</function> function opens
a file with form data. This file must contain the data as returned
from a PDF form. Currently, the file has to be created 'manually'
by using <function>fopen</function> and writing the content
of HTTP_FDF_DATA with <function>fwrite</function> into it.
A mechanism like for HTML form data where for each input
field a variable is created does not exist.</para>
<para>
<example>
<title>Accessing the form data</title>
<programlisting>
<![CDATA[
<?php
// Save the FDF data into a temp file
$fdffp = fopen("test.fdf", "w");
fwrite($fdffp, $HTTP_FDF_DATA, strlen($HTTP_FDF_DATA));
fclose($fdffp);
// Open temp file and evaluate data
$fdf = fdf_open("test.fdf");
...
fdf_close($fdf);
?>
]]>
</programlisting>
</example></para>
<para>
See also <function>fdf_close</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-close">
<refnamediv>
<refname>fdf_close</refname>
<refpurpose>Close an FDF document</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_close</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_close</function> function closes the FDF document.</para>
<para>
See also <function>fdf_open</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-create">
<refnamediv>
<refname>fdf_create</refname>
<refpurpose>Create a new FDF document</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>fdf_create</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_create</function> creates a new
FDF document. This function is needed if one would like to
populate input fields in a PDF document with data.</para>
<para>
<example>
<title>Populating a PDF document</title>
<programlisting>
<![CDATA[
<?php
$outfdf = fdf_create();
fdf_set_value($outfdf, "volume", $volume, 0);
fdf_set_file($outfdf, "http:/testfdf/resultlabel.pdf");
fdf_save($outfdf, "outtest.fdf");
fdf_close($outfdf);
Header("Content-type: application/vnd.fdf");
$fp = fopen("outtest.fdf", "r");
fpassthru($fp);
unlink("outtest.fdf");
?>
]]>
</programlisting>
</example></para>
<para>
See also <function>fdf_close</function>,
<function>fdf_save</function>,
<function>fdf_open</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-save">
<refnamediv>
<refname>fdf_save</refname>
<refpurpose>Save a FDF document</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>fdf_save</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_save</function> function saves
a FDF document.
The FDF Toolkit provides a way to output the document to stdout if
the parameter <parameter>filename</parameter>
is '.'. This does not work if PHP is used as an apache module.
In such a case one will have to write to a file and use e.g.
<function>fpassthru</function> to output it.</para>
<para>
See also <function>fdf_close</function> and example for
<function>fdf_create</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-get-value">
<refnamediv>
<refname>fdf_get_value</refname>
<refpurpose>Get the value of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>fdf_get_value</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>fieldname</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_get_value</function> function returns the
value of a field.</para>
<para>
See also <function>fdf_set_value</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-value">
<refnamediv>
<refname>fdf_set_value</refname>
<refpurpose>Set the value of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_value</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>fieldname</parameter></paramdef>
<paramdef>string <parameter>value</parameter></paramdef>
<paramdef>int <parameter>isName</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_value</function> function sets the
value of a field. The last parameter determines if the field value
is to be converted to a PDF Name (<parameter>isName</parameter> = 1)
or set to a PDF String (<parameter>isName</parameter> = 0).</para>
<para>
See also <function>fdf_get_value</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-next-field-name">
<refnamediv>
<refname>fdf_next_field_name</refname>
<refpurpose>Get the next field name</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>fdf_next_field_name</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string
<parameter><optional>fieldname</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_next_field_name</function> function returns the
name of the field after the field in
<parameter>fieldname</parameter> or the field name of the first field
if the second paramter is &null;.</para>
<para>
See also <function>fdf_set_value</function>,
<function>fdf_get_value</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-ap">
<refnamediv>
<refname>fdf_set_ap</refname>
<refpurpose>Set the appearance of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_ap</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>field_name</parameter></paramdef>
<paramdef>int <parameter>face</parameter></paramdef>
<paramdef>string <parameter>filename</parameter></paramdef>
<paramdef>int <parameter>page_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_ap</function> function sets the
appearance of a field (i.e. the value of the /AP key).
The possible values of <parameter>face</parameter>
are 1=FDFNormalAP, 2=FDFRolloverAP, 3=FDFDownAP.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-status">
<refnamediv>
<refname>fdf_set_status</refname>
<refpurpose>Set the value of the /STATUS key</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_status</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>status</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_status</function> sets the value
of the /STATUS key.</para>
<para>
See also <function>fdf_get_status</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-get-status">
<refnamediv>
<refname>fdf_get_status</refname>
<refpurpose>Get the value of the /STATUS key</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>fdf_get_status</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_get_status</function> returns the value
of the /STATUS key.</para>
<para>
See also <function>fdf_set_status</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-file">
<refnamediv>
<refname>fdf_set_file</refname>
<refpurpose>Set the value of the /F key</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_file</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>filename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_file</function> sets the value
of the /F key. The /F key is just a reference to a PDF form
which is to be populated with data.
In a web environment it is a URL (e.g. http:/testfdf/resultlabel.pdf).</para>
<para>
See also <function>fdf_get_file</function> and example for
<function>fdf_create</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-get-file">
<refnamediv>
<refname>fdf_get_file</refname>
<refpurpose>Get the value of the /F key</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>fdf_get_file</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_file</function> returns the value
of the /F key.</para>
<para>
See also <function>fdf_set_file</function>.</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-flags">
<refnamediv>
<refname>fdf_set_flags</refname>
<refpurpose>Sets a flag of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_flags</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>fieldname</parameter></paramdef>
<paramdef>int <parameter>whichFlags</parameter></paramdef>
<paramdef>int <parameter>newFlags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_flags</function> sets certain flags
of the given field <parameter>fieldname</parameter>.
</para>
<para>
See also <function>fdf_set_opt</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-opt">
<refnamediv>
<refname>fdf_set_opt</refname>
<refpurpose>Sets an option of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_opt</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>fieldname</parameter></paramdef>
<paramdef>int <parameter>element</parameter></paramdef>
<paramdef>string <parameter>str1</parameter></paramdef>
<paramdef>string <parameter>str2</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_opt</function> sets options
of the given field <parameter>fieldname</parameter>.
</para>
<para>
See also <function>fdf_set_flags</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-submit-form-action">
<refnamediv>
<refname>fdf_set_submit_form_action</refname>
<refpurpose>Sets a submit form action of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_submit_form_action</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>fieldname</parameter></paramdef>
<paramdef>int <parameter>trigger</parameter></paramdef>
<paramdef>string <parameter>script</parameter></paramdef>
<paramdef>int <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>fdf_set_submit_form_action</function> sets a submit form
action for the given field <parameter>fieldname</parameter>.
</para>
<para>
See also <function>fdf_set_javascript_action</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-javascript-action">
<refnamediv>
<refname>fdf_set_javascript_action</refname>
<refpurpose>Sets an javascript action of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_javascript_action</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>fieldname</parameter></paramdef>
<paramdef>int <parameter>trigger</parameter></paramdef>
<paramdef>string <parameter>script</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>fdf_set_javascript_action</function> sets a javascript
action for the given field <parameter>fieldname</parameter>.
</para>
<para>
See also <function>fdf_set_submit_form_action</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.fdf-set-encoding">
<refnamediv>
<refname>fdf_set_encoding</refname>
<refpurpose>Sets FDF character encoding</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_set_encoding</function></funcdef>
<paramdef>int <parameter>fdf_document</parameter></paramdef>
<paramdef>string <parameter>encoding</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>fdf_set_encoding</function> sets the character
encoding in FDF document <parameter>fdf_document</parameter>.
<parameter>encoding</parameter> should be the valid encoding
name. The valid encoding name in Acrobat 5.0 are
"<literal>Shift-JIS</literal>", "<literal>UHC</literal>",
"<literal>GBK</literal>","<literal>BigFive</literal>".
</para>
<para>
The <function>fdf_set_encoding</function> is available in
PHP 4.1.0 or later.
</para>
</refsect1>
</refentry>
<refentry id='function.fdf-add-template'>
<refnamediv>
<refname>fdf_add_template</refname>
<refpurpose>Adds a template into the FDF document</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>fdf_add_template</function></funcdef>
<paramdef>int <parameter>fdfdoc</parameter></paramdef>
<paramdef>int <parameter>newpage</parameter></paramdef>
<paramdef>string <parameter>filename</parameter></paramdef>
<paramdef>string <parameter>template</parameter></paramdef>
<paramdef>int <parameter>rename</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->