CVS update: phpdoc/functions

Date: Thursday July 1, 1999 @ 11:42 Author: steinm Update of /repository/phpdoc/functions In directory php:/tmp/cvs-serv28698/functions Modified Files: fdf.sgml pdf.sgml Log Message: - more documentation Index: phpdoc/functions/fdf.sgml diff -u phpdoc/functions/fdf.sgml:1.4 phpdoc/functions/fdf.sgml:1.5 --- phpdoc/functions/fdf.sgml:1.4 Sun Jun 27 21:26:21 1999 +++ phpdoc/functions/fdf.sgml Thu Jul 1 11:42:14 1999 @@ -6,16 +6,82 @@ <simpara> Forms Data Format (FDF) is a format for handling - forms within PDF documents. You can read the documentation at <ulink + forms within PDF documents. You should read the documentation at <ulink url="http://partners.adobe.com/asn/developer/acrosdk/main.html">http://partners.adobe.com/asn/developer/acrosdk/main.html</ulink> for more information on what FDF is and how it is used in general. + <note><simpara> + Currently Adobe only provides a libc5 compatible version for Linux. Tests + with glibc2 resulted in a segmentation fault. If somebody is able to + make it work, please comment on this page. + </simpara></note> + + <simpara> + The general idea of FDF is similar to HTML forms. The diffence is + basically the format how filled in 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 application/vnd.fdf. 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> + The following examples shows just the evaluation of form data. + <simpara> + <example> + <title>Evaluating a FDF document</title> + <programlisting> +&lt;?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 '&lt;B>$volume&lt;/B>'&lt;BR>"; + +$date = fdf_get_value($fdf, "date"); +echo "The date field has the value '&lt;B>$date&lt;/B>'&lt;BR>"; + +$comment = fdf_get_value($fdf, "comment"); +echo "The comment field has the value '&lt;B>$comment&lt;/B>'&lt;BR>"; + +if(fdf_get_value($fdf, "show_publisher") == "On") { + $publisher = fdf_get_value($fdf, "publisher"); + echo "The publisher field has the value '&lt;B>$publisher&lt;/B>'&lt;BR>"; +} else + echo "Publisher shall not be shown.&lt;BR>"; + +if(fdf_get_value($fdf, "show_preparer") == "On") { + $preparer = fdf_get_value($fdf, "preparer"); + echo "The preparer field has the value '&lt;B>$preparer&lt;/B>'&lt;BR>"; +} else + echo "Preparer shall not be shown.&lt;BR>"; +fdf_close($fdf); +?> + </programlisting> + </example> + </partintro> <refentry id="function.fdf-open"> <refnamediv> <refname>fdf_open</refname> - <refpurpose>Open a new FDF document</refpurpose> + <refpurpose>Open a FDF document</refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -25,8 +91,30 @@ </funcsynopsis> <para> The <function>fdf_open</function> function opens - a new FDF document. If the parameter <parameter>filename</parameter> - is '.' the file is read from stdin. + 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> + <example> + <title>Accessing the form data</title> + <programlisting> +&lt;?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> See also <function>fdf_close</function>. @@ -67,7 +155,27 @@ </funcsynopsis> <para> The <function>fdf_create</function> creates a new - FDF document. + FDF document. This function is needed if one would like to + populate input fields in a PDF document with data. + <para> + <example> + <title>Populating a PDF document</title> + <programlisting> +&lt;?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> See also <function>fdf_close</function>, <function>fdf_save</function>, @@ -89,11 +197,16 @@ </funcsynopsis> <para> The <function>fdf_save</function> function saves - a FDF document. If the parameter <parameter>filename</parameter> - is '.' the file is written to stdout. + 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> - See also <function>fdf_close</function>. + See also <function>fdf_close</function> and example for + <function>fdf_create</function>. </refsect1> </refentry> @@ -122,13 +235,13 @@ <refentry id="function.fdf-set-value"> <refnamediv> - <refname>fdf_get_value</refname> + <refname>fdf_set_value</refname> <refpurpose>Set the value of a field</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> - <funcdef>void <function>fdf_get_value</function></funcdef> + <funcdef>void <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> @@ -160,7 +273,7 @@ </funcsynopsis> <para> The <function>fdf_next_field_name</function> function returns the - name of the field string after the field in parameter + 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. @@ -252,10 +365,13 @@ </funcsynopsis> <para> The <function>fdf_set_file</function> sets the value - of the /F key. + 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> - See also <function>fdf_get_file</function>. + See also <function>fdf_get_file</function> and example for + <function>fdf_create</function>. </refsect1> </refentry> Index: phpdoc/functions/pdf.sgml diff -u phpdoc/functions/pdf.sgml:1.7 phpdoc/functions/pdf.sgml:1.8 --- phpdoc/functions/pdf.sgml:1.7 Wed Jun 30 17:26:08 1999 +++ phpdoc/functions/pdf.sgml Thu Jul 1 11:42:14 1999 @@ -1689,7 +1689,7 @@ <simpara> Unfortunately pdflib does not make a copy of the string, which forces PHP to allocate the memory. Currently this piece of memory is not - been freed by any PDF function but will be taken care of by the + been freed by any PDF function but it will be taken care of by the PHP memory manager. </refsect1> @@ -1710,31 +1710,36 @@ <para> The <function>PDF_set_transition</function> function set the transition between following pages. The value of <parameter>transition</parameter> - can be 0 for none, + can be - <orderedlist> - <listitem><para> + <simplelist> + <member> + 0 for none, + </member> + <member> 1 for two lines sweeping across the screen reveal the page, - </listitem> - <listitem><para> + </member> + <member> 2 for multiple lines sweeping across the screen reveal the page, - </listitem> - <listitem><para> + </member> + <member> 3 for a box reveals the page, - </listitem> - <listitem><para> + </member> + <member> 4 for a single line sweeping across the screen reveals the page, - </listitem> - <listitem><para> + </member> + <member> 5 for the old page dissolves to reveal the page, - </listitem> - <listitem><para> + </member> + <member> 6 for the dissolve effect moves from one screen edge to another, - </listitem> - <listitem><para> + </member> + <member> 7 for the old page is simply replaced by the new page (default) - </listitem> - </orderedlist> + </member> + </simplelist> + <para> + See also <function>PDF_set_duration</function>. </refsect1> </refentry> @@ -1753,6 +1758,8 @@ <para> The <function>PDF_set_duration</function> function set the duration between following pages in seconds. + <para> + See also <function>PDF_set_transition</function>. </refsect1> </refentry> @@ -1770,8 +1777,9 @@ </funcsynopsis> <para> The <function>PDF_open_gif</function> function opens an image stored - in the file with the name <parameter>file name</parameter>. - The format of the image has to be jpeg. + in the file with the name <parameter>filename</parameter>. + The format of the image has to be gif. The function returns a pdf + image identifier. <example> <title>Including a gif image</title> @@ -1809,7 +1817,8 @@ <para> The <function>PDF_open_memory_image</function> function takes an image created with the PHP's image functions and makes it available - for the pdf document. + for the pdf document. The function returns a pdf + image identifier. <example> <title>Including a memory image</title> @@ -1819,6 +1828,7 @@ $col = ImageColorAllocate($im, 80, 45, 190); ImageFill($im, 10, 10, $col); $pim = PDF_open_memory_image($pdf, $im); +ImageDestroy($im); pdf_place_image($pdf, $pim, 100, 100, 1); pdf_close_image($pdf, $pim); ?> @@ -1849,8 +1859,9 @@ </funcsynopsis> <para> The <function>PDF_open_jpeg</function> function opens an image stored - in the file with the name <parameter>file name</parameter>. - The format of the image has to be jpeg. + in the file with the name <parameter>filename</parameter>. + The format of the image has to be jpeg. The function returns a pdf + image identifier. <para> See also <function>PDF_close_image</function>, <function>PDF_open_gif</function>, @@ -1925,9 +1936,14 @@ in the PDF file without showing it. The stored image can be displayed with the <function>PDF_execute_image</function> function as many times as needed. This is useful when using the same - image multiple times in order to keep the file size small. + image multiple times in order to keep the file size small. Using + <function>PDF_put_image</function> and + <function>PDF_execute_image</function> is highly recommended for + larger images (several kb) if they show up more than once in the + document. <para> - See also <function>PDF_place_image</function>, + See also <function>PDF_put_image</function>, + <function>PDF_place_image</function>, <function>PDF_execute_image</function>. </refsect1> </refentry>