PDFpirate Community/ doc/ creating plugins generic

Users

About
Get Involved

Developers

Documentation
Source Code
Roadmap

Organization

Funding
In the Media

Forum

Creating PDFpriate Plugins (Generic)

Plugins add functionality to PDFpirate. Convert WEB to PDF and Remove Restrictions are examples of plugins.

Notice this document is only an outline of how to create PDFpirate plugins. See it as a complement to the corresponding guide dealing with the specifics of the language you've chosen to create your plugin in.

Working environment

This will be, in most of the cases, your local installation of PDFpirate. Check the documentation page to find out how to install PDFpirate.

Alternatively you can post your plugin on the forum and we'll be happing to test it for you.

Plugin directory

All plugins exist in their separate folders inside plugin/ directory. Create one for your work alongside the others.

/plugins/
convert_WEB_to_PDF
remove_restrictions
my_plugin

Apache2 settings

Make sure apache2 knows how to handle your files. It's usually as simple as setting the right handler.

## Settings for /plugins/my_plugin directory
<Directory /srv/www/pdfpirate/plugins/my_plugin>
    <FilesMatch ".extension">
        SetHandler      handler
    </FilesMatch>
</Directory>

/lib* folders

If you think some of your files may be reused by other plugin authors please put them in the appropriate /lib* folder.

/lib # for static files
/lib_mason  # for mason files
/lib_php   # for php files
etc.

pdfpirate.config

PDFpirate configuration file resides in / folder. It's 3 columns wide, ';;;' (triple semicolon) separated, text file. Please check it out to find out how to implement configurable parts of your plugin. This file should be parsed and loaded into memory in the initialization part of your scripts.

*.strings files

To simplify internationalization and translations PDFpirate uses custom .strings files where the textual data is being kept. Please check /lib/i18n/English.strings file for details. We expect you to use this system when writing plugins. Again, it's 3 columns wide, ';;;' (triple semicolon) separated, text file and it should be parsed and loaded into memory in the initialization part of your scripts.

To find out which .strings file to load in please check for the existence of PDFpirate_language_data cookie. If present it'll tell you about user language preferences. The cookie's value field contains set of 3 key-value pairs and it's written in the following format: language&English&language_subtag&en&text_direction&ltr.

language => language name
language_subtag => ISO 639-1 language subtag
text_direction => ltr or rtl

If the PDFpirate_language_data cookie is absent, run /lib_mason/init.mhtml script to set it up.

<iframe style="display: none;" src="/lib_mason/init.mhtml"></iframe>

If that fails, only load in English.strings.

Notice that you should always load in English.strings file first and then overwrite the read data with the language specific .strings file. This is in case of partial translations.

HTML Version

Please use elements of HTML5 and CSS3 in a manner that they don't break functionality in older browsers. Obviously we're not talking here about making your plugin compatible with IE6. Be sensible.

HTML Template

<!DOCTYPE html>
<html dir="text_direction" lang="language_subtag">
<head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    <link rel="stylesheet" href="/lib/style.css">
    <link rel="stylesheet" href="/plugins/my_plugin/my_plugin.css">
    <script src="/plugins/my_plugin/my_plugin.js"></script>
    <title>PDFpirate, Do Something With Your PDF</title>  # check http://www.w3.org/International/tutorials/bidi-xhtml/ to find out how to change text direction in title
</head>
<body>
    <div id="the_container">
        # Plugin code goes here
    </div>
</body>
</html>

API

This is not a requirement but please consider making functions of your plugin available through API. It's always better to start codding having this on mind rather than trying to implement it at a later time.

Licencing

We'd like you to use AGPL.

Submit your plugin

Simply create a patch file against the latest version in repository and post in on the forum. After successful revision you should find your plugin included with the next release of PDFpirate.