EmbedPDFPlugin < TWiki

TWiki Web>EmbedPDFPlugin (2011-05-25, TWikiAdminUser) (raw view)EditAttach
---+!! <nop>%TOPIC%
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/EmbedPDFPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/EmbedPDFPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%
 
---++ Introduction

Many browsers can show PDF documents embedded just like pictures within HTML documents using the =&lt;object&gt;= HTML tag. Unfortunately, they are usually unable to detect the preferred (screen) size and aspect ratio of the PDF document and display only a little unreadable thumbnail version of the PDF file. 

This plugin adds =%<nop>EMBEDPDF{...}%= and =%<nop>EMBEDPDFSIZE{...}%= variables. These variables are helpful for embedding PDF documents in TWiki webs. =%<nop>EMBEDPDF{...}%= will create an =&lt;object&gt;= HTML tag to show the specified PDF file in a reasonable size (as specified within that PDF file). =%<nop>EMBEDPDFSIZE{...}%= will expand to the width and height of the file.

---++ Caution

   1 This plugin read files from your disk using =TWiki::Func::readFile()=. It may be possible for an attacker to gain access to arbitrary files on your disk. I have taken some simple precautions to prevent this, but I'm not sure whether they are sufficient. 
   1 TWiki may run out of memory if the PDF file referenced is very large. It is mainly intended for small single-page PDF files.

You might want to restrict _write_ access to your Web to prevent intruders from exploiting possible vulnerabilities. I do not think exploits are possible through read-only access. Use at your own risk. 

---++ Syntax Rules

   * =%<nop>EMBEDPDF{ &lt;filename&gt; }%=
   * =%<nop>EMBEDPDFSIZE{ &lt;filename&gt; }%=
      * =&lt;filename&gt;= is the file name of an attachment of the current topic. 

---++ Examples

Assume that test.pdf has a height of 40 points and a width of 100 points. Then:
   * =%<nop>EMBEDPDF{ test }%= expands to %BR%
     =&lt;object data="%<nop>ATTACHURLPATH%/test.pdf" width="100" height="40" type="application/pdf"&gt;= %BR%
     =&lt;param name="src" value="%<nop>ATTACHURLPATH%/test.pdf" /&gt;= %BR%
     =&lt;a href="%ATTACHURLPATH%/pdf.pdf"&gt;pdf.pdf&lt;/a&gt;= %BR%
     =&lt;/object&gt;=
   * =%<nop>EMBEDPDFSIZE{ test }%= expands to %BR%
     =width="100" height="40"=
Note that the =.pdf= extension is automatically added to the attachment name.

The plugin checks the user agent setting reported by your browser to detect IE. For IE, the width and height will be enlarged since IE displays the PDF viewer controls within the HTML document along with the PDF document itself.

---++ <nop>%TOPIC% Global Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>INTERWIKIPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Embed PDF documents in TWiki pages

   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0

   * Create a link under every embedded PDF file with the specified link text if set (useful for browsers that don't know how to embed PDF):
      * Set LINKTEXT = (click here to display this PDF file by itself) 

   * Check whether a pre-rendered image of the PDF file with the specified extension is available, and if so, embed the image rather than the PDF file itself:
      * Set PRERENDERED = jpg

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
 
   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==pub/TWiki/%TOPIC%/pdf.pdf== | Sample pdf file |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Test if the installation was successful: The following two pictures should look the same (assuming you have a PDF plugin installed in your browser)
         * Embed tag created using =%<nop>EMBEDPDF{ pdf }%=: %BR% %EMBEDPDF{ pdf }%
         * Hard coded embed tag: %BR% <object data="%ATTACHURLPATH%/pdf.pdf" width="216" height="31" type="application/pdf"><param name="src" value="%ATTACHURLPATH%/pdf.pdf" /><a href="%ATTACHURLPATH%/pdf.pdf">pdf.pdf</a></object>
      * The width and height of %ATTACHURL%/pdf.pdf as determined by =%<nop>EMBEDPDFSIZE{ pdf }%= are as follows:
         * %EMBEDPDFSIZE{ pdf }%
      * Here is a pdf file for which we have a pre-rendered version available. The actual pdf file is missing, so the link under the image is dead: %BR% %EMBEDPDF{ pdf-prerendered }%

---++ Plugin Info

|  Plugin Author: | TWiki:Main.JohannesMartin |
|  Copyright: | &copy; 2003 TWiki:Main.JohannesMartin <br /> &copy; 2008-2011 TWiki:TWiki.TWikiContributor |
|  Plugin Version: | 2011-05-10 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2011-05-10: | TWikibug:Item6701: Change &lt;embed&gt; tag to &lt;object&gt; tag; doc improvements -- TWiki:Main.PeterThoeny |
|  07 Mar 2003: | added support for IE and link text |
|  06 Mar 2003: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.080 |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ TWiki:Plugins.EmbedPDFPluginDev, %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
Attachments
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
jpg	pdf-prerendered.jpg	manage	3.6 K	2011-05-11 - 07:31	TWikiAdminUser	Saved by install script
Topic revision: r2 - 2011-05-25 - 17:33:24 - TWikiAdminUser
TWiki
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.EmbedPDFPlugin