More about WaterWoo PDF Premium

WaterWoo does its magic using the open-source TCPDF and TCPDI libraries (not developed or maintained by WaterWoo dev). TCPDI parses the existing PDF (assuming it is unencrypted and uncorrupted), recreating it in memory, and TCPDF applies your watermark. Regretfully, TCPDI is unable to parse certain PDF elements into memory, such as internal links and forms. However, hopefully this feature will be more stable in a future TCPDI release. Understanding a little about how TCPDI and TCPDF come into play, using PHP memory, might help you to create the most effective and efficient watermarks.

View the WaterWoo changelog here.

Recommendations

PHP Version

You should be running at least PHP version 5.4 for all features of EDDiMark PDF to work, but higher than that for it to work WELL. WaterWoo PDF recommends you run PHP version 7.2 or higher. WaterWoo PDF is PHP version 7.2 compatible, so don’t hesitate to upgrade after making backups. PHP 7.0 is twice as fast for WordPress as PHP 5.6!

Increase Memory

Increase your PHP memory allotment to at least 64MB. In fact, put it as high as your host will allow. If your host does not allow more than 16 or 32, it might be a good time to switch hosts or servers. If you expect your PDF to take more than 30 seconds to parse (gasp!), you may also need to increase your PHP max_execution_time.

Hide your Precious Files

This is obviously important. Upload your files to an uploads folder, then consider moving it. Also, consider adding a blank index.html file to the folder containing your PDF and use .htaccess to “deny from all”.

Large PDFs?

If you are having trouble sharing large PDF files, keep in mind that your hosting plan needs to be robust enough to support the memory and bandwidth necessary to fulfill these requests. Try these suggestions: https://tcpdf.org/docs/performances/. (FYI Thai characters are already disabled in Waterwoo.) Keep your watermarks simple (avoid HTML if possible) and use non-Unicode fonts if possible (Helvetica, Times, Courier).

Maybe it’s time for a server upgrade?

Margins

Waterwoo comes with default margins to keep your watermark inside an area on the page. These are 10mm left/right, and 10mm top/bottom.

If you would like to remove this restriction, set the margins to 0. If you would like to move things in on the page, set the margins higher.

The XY fine tuners accomplish the same thing; however, they cannot remove the margins. So a margins setting was added primarily for those people wanting to remove the margins.

Simple Shortcodes

Simple shortcodes available are [FIRSTNAME] [LASTNAME] [BUSINESSNAME] [EMAIL] [PHONE] [DATE] [ORDERNUMBER]. Using one of these in your overlay or footer text will cause the shortcode to be replaced by the customer data during checkout and watermarking.

Keep in mind if you do not solicit the “businessname” field or make it mandatory, and the customer leaves it blank, the [businessname] shortcode will leave an empty spot in the watermark if you use it. The other simple shortcode fields are guaranteed to come through unless you (or your theme) changes that.

Here is more information about how to use your theme’s function.php file to alter WooCommerce core fields

Future [DATE] Shortcodes

To add a future date marked from the date of purchase, you can use the [DATE-#YRS] [DATE-#MOS] [DATE-#WKS] [DATE-#DAYS] shortcode, where # is replaced with the number of days/months/weeks/years desired. This shortcode is based on 30-day months, and 365-day years, so it might be best to use days if you need precision.

Examples

[DATE-365DAYS] would be 365 days from the checkout date.

[DATE-2YRS] would be 730 days from the checkout date, but does not take into account a leap year.

Number Sold [PRODUCT-#] Shortcodes

To add in the number of a product purchased, you can use the [PRODUCT-###] shortcode, where ### is replaced with the numeral product ID. You can find the product ID listed underneath the product title on your main WooCommerce Products listing page (hover over the desired product title to see the ID), or by hovering over the product title and looking at the browser status bar (lower screen, look for the number after “post=”). This must be an item found in the cart in order to work, otherwise the shortcode comes up blank. This shortcode will not work with the testing feature.

Starting with version 2.0.3, for users of WooCommerce 2.7+, is a [PRODUCT-###] wildcard shortcode… Instead of having to enter a product number, you can just enter exactly, just [PRODUCT-###]!

Opacity Shortcodes

The {OPAC} shortcode — and watermarking with opacity — is totally unique to this plugin is very helpful for people not wanting to obscure their PDF content, since the watermark sits on top. It doesn’t always play nice with HTML in your watermark, so sometimes some rearranging will need to be done. Consider wrapping your HTML inside {OPAC} tags if trying to get opacity, if the inverse isn’t working.

Examples:

{OPAC-0.5}This is sample text{/OPAC}

This is sample text” will be at 50% transparency. The tag needs a dash, then a number representing the fraction of 100% opacity.

{OPAC-0.1}This is very transparent text{/OPAC}

This is very transparent text” will be at 10% transparency.

Note there is an open tag and a close tag around the text. If text does not wrap when using this tag, you may have to use HTML <br> tags. {OPAC} tag is still beta.

Text alignment

To style a link <a> or tag when using HTML, the following inline CSS options are available: font-style:italic, font-weight:bold, and text-align:center and text-align:right. This feature allows you to center text – yay!

Here’s an example of the code used to center some text.

Hooks (actions/filters)

Starting in WaterWoo version 2.0, hooks were added to make it possible to adjust WaterWoo to carry out some of your specific needs. The hooks are NOT supported by WaterWoo staff unless you find a bug or need arguments added. We will not be able to write actions and filter code for you. The hooks were placed for your developer’s convenience.

‘ wwpdf_watermark_use_uploads_dir ‘ filter to choose where temporary files are stored. More here.

‘ wwpdf_add_custom_font ‘ and ‘ wwpdf_font_decode ‘ filters, more here

‘ wwpdf_download_file_name ‘ filter, you’ll know it when you need it… more here

‘ wwpdf_add_barcode ‘ filter for maybe adding barcodes

‘ wwpdf_file_cleanup ‘ action to clean up residual files on the server if using Redirect download method. More here.

‘ wwpdf_do_cleanup ‘ filter to maybe prevent cleanup of files served via forced or xsendfile download. Added in version 2.2. More here.

‘ waterwoo_settings_array ‘ filter to allow for manipulation of main watermarking settings (possibly to add settings). Added in version 2.2

‘ waterwoo_overlay_filter ‘ and ‘ waterwoo_footer_filter ‘ filters to allow for manipulation of watermarks. Added in version 2.2

‘ wwpdf_filter_overlay’ and ‘ wwpdf_filter_footer ‘ filters to allow for manipulation of watermarks were added in version 2.5 and fire after the previously mentioned watermark filters. With these hooks you can possibly add in your own shortcodes for custom checkout fields.

‘ wwpdf_set_zoom_mode ‘ and ‘ wwpdf_set_viewer_preferences ‘ filters for setting PDF viewing preferences via TCPDF. Added in version 2.2. Examples of SetDisplayMode() in use. More on TCPDF setViewerPreferences() here.

‘ wwpdf_set_password ‘ filter for creating alternate passwords. Added in version 2.5 More here.

Fonts (maybe adding)

To run watermarking with your custom font, you can run the filter “wwpdf_add_custom_font”. Font must be added to TCPDF first using AddFont(). Please read TCPDF docs. Fonts which come with TCPDF can also be added back in to the fonts folder; they were removed to keep this plugin as lightweight as possible. This is in development and not a supported feature.

function my_custom_font_name() {
    $font = TCPDF_FONTS::addTTFfont( $font_file, $font_type, $enc, $flags, $outpath, $platid, $encid, $addcbbox, $linkbox );
    return $font;
}
add_filter( 'wwpdf_add_custom_font', ‘my_custom_font_name’, 10, 1 );

Keep in mind the $font value you return will be run in SetFont() while WaterWoo does its magic.

addTTFfont() parameters:

$fontfile (string) Font file (full path).
$fonttype (string) Font type. Leave empty for autodetect mode. Valid values are: TrueTypeUnicode, TrueType, Type1, CID0JP = CID-0 Japanese, CID0KR = CID-0 Korean, CID0CS = CID-0 Chinese Simplified, CID0CT = CID-0 Chinese Traditional.
$enc (string) Name of the encoding table to use. Leave empty for default mode. Omit this parameter for TrueType Unicode and symbolic fonts like Symbol or ZapfDingBats.
$flags (int) Unsigned 32-bit integer containing flags specifying various characteristics of the font (PDF32000:2008 – 9.8.2 Font Descriptor Flags): +1 for fixed font; +4 for symbol or +32 for non-symbol; +64 for italic. Fixed and Italic mode are generally autodetected so you have to set it to 32 = non-symbolic font (default) or 4 = symbolic font.
$outpath (string) Output path for generated font files (must be writeable by the web server). Leave empty for default font folder.
$platid (int) Platform ID for CMAP table to extract (when building a Unicode font for Windows this value should be 3, for Macintosh should be 1).
$encid (int) Encoding ID for CMAP table to extract (when building a Unicode font for Windows this value should be 1, for Macintosh should be 0). When Platform ID is 3, legal values for Encoding ID are: 0=Symbol, 1=Unicode, 2=ShiftJIS, 3=PRC, 4=Big5, 5=Wansung, 6=Johab, 7=Reserved, 8=Reserved, 9=Reserved, 10=UCS-4.
$addcbbox (boolean) If true includes the character bounding box information on the php font file.
$link (boolean) If true link to system font instead of copying the font data (not transportable) – Note: do not work with Type1 fonts.

If your overlay or footer are not looking right after you’ve added a new font, the filter ‘wwpdf_font_decode’ might need to be used to add html_entity_decode() around your overlay or footer input.

Encryption

Be aware that protecting a PDF requires to encrypt it, which increases the processing time a lot. This can cause a PHP time-out in some cases, especially if the document contains images or fonts.

The file will be automatically encrypted if a password is set. If you don’t set any password, the document will open as usual.
If you set a user password, the PDF viewer will ask for it before displaying the document.
Typing the word “email” into the password field in WaterWoo settings will force the end user to open the PDF with the buyer’s email address. Alternatively the ‘wwpdf_set_password’ hook can be used to set a different type of password if desired, see below.

The permission array is composed of values taken from the following ones (specify the ones you want to block):

  • The following are set together:
    • print : Print the document
    • print‑high : Print the document to a representation from which a faithful digital copy of the PDF content could be generated. When this is not set, printing is limited to a low-level representation of the appearance, possibly of degraded quality.
  • The following are set together:
    • modify : Modify the contents of the document by operations other than those controlled by ‘fill-forms’, ‘extract’ and ‘assemble’
    • assemble : Assemble the document (insert, rotate, or delete pages and create bookmarks or thumbnail images), even if ‘modify’ is not set
  • copy : Copy or otherwise extract text and graphics from the document
  • The following are set together:
    • annot‑forms : Add or modify text annotations, fill in interactive form fields, and, if ‘modify’ is also set, create or modify interactive form fields (including signature fields)
    • Fill‑forms : Fill in existing interactive form fields (including signature fields), even if ‘annot-forms’ is not specified

More information about SetProtection() here and here.

Recommended you allow:
  • Copy. If not allowed this document will not be readable by humans who rely on screen readers instead of their eyes to read. Keep it accessible!

Passwords

Here’s an example of how to use the ‘wwpdf_set_password’ filter hook to set up your own password. In this example it uses the customer’s billing phone. It would be important in this instance to require a phone number from your customers!

function my_own_password_function( $password, $order_id ) {
    $order = wc_get_order( $order_id );
    $order_data = $order->get_data();
    $phone = $order_data['billing']['phone']; // might be wise to set up a fallback in case this is empty
    // maybe remove any non-digit character from phone number
    $password = preg_replace('/D+/', '', $phone);
    // return phone as password
    return $password;
}
add_filter( 'wwpdf_set_password', 'my_own_password_function', 10, 2 );

Learn more about order/customer data that would be accessible using the $order_id argument provided in this hook.

Barcodes (maybe adding)

To add a barcode somewhere on your page, you can use the ‘wwpdf_add_barcode’ filter. An example goes like this:

function my_barcode_function( $barcode_array ) {
    return array( '2D', 'Test Barcode', 'QRCODE', 100, 230, 30, 30 );
}
add_filter( 'wwpdf_add_barcode', 'my_barcode_function', 10, 1 );

The ‘my_barcode_function’ function returns an array used by WaterWoo to create a barcode.

  1. The first argument accepts either ‘1D’ or ‘2D’.
  2. The second argument will be your barcode contents.
  3. The third argument states the TYPE of barcode (please refer to TCPDF documentation for 1D vs 2D barcode setup and appropriate names for barcode types.)
  4. The fourth argument is X-axis placement. In the example, I have it set 10cm (100mm) over to the right.
  5. The fifth argument is Y-axis placement. In the example, I have it set 23cm (230mm) over to the right.
  6. The sixth argument is the width of the barcode in millimeters.
  7. The seventh argument is height of the barcode in millimeters.

As of WaterWoo Premium v2.0, no order information is passed to this filter.

What happens to files on the server…

If you choose the WooCommerce “Force” download method, the file is watermarked, download is forced, and the temporary file is deleted.

Otherwise, if you have chosen “Redirect” or “XSendFile” download method, the file is watermarked, the buyer is redirected to the temporary file, and the file remains in a temporary folder. It is recommended you set up a cron to keep this folder empty.

If you want to store watermarked files in your WordPress “/uploads” folder (in a subfolder called “/waterwoo-pdf”) use the following hook:

add_filter( 'wwpdf_watermark_use_uploads_dir', '__return_true' );

You do not need to create the folder, the plugin will do that for you.

File Name Change

Like how filenames used to be customized with date and order number? I took this away with version 2.0 for folks not using the wp-content directory to store watermarked files, and for folks using forced downloads, BECAUSE… if a file doesn’t exist anymore on your end, what does it matter what it is called. The customer can rename a file anything they want, so it just made sense to fall back to your intended name.
Don’t fret! Function my_custom_PDF_filename() would makes it like how it used to be before v2.0.

function my_custom_PDF_filename( $file_name, $order_num ) {

    $file_name = str_replace( '.pdf', '', $file_name ) . '_' . time() . '_' . $order_num . '.pdf';
    return $file_name;
}
add_filter( 'wwpdf_download_file_name', 'my_custom_PDF_filename', 10, 2 );

This filter hook could also be used to customized your customer’s file download file name in other ways. That’s up to you.

Clean Up files after Redirect Download

The ‘wwpdf_file_cleanup’ action hook will maybe allow you to set up a function or cron to deal with files stored temporarily in the special wp-content/uploads/waterwoo-pdf folder.

add_action( 'wwpdf_file_cleanup', 'your_custom_function', $file_path);

The ‘wwpdf_do_cleanup’ filter will allow you to turn OFF file clean up for forced downloads:

add_filter( 'wwpdf_do_cleanup', __return_false );

Redirect and X-Accel-Redirect must have files on the server for the customer to fetch. It’s recommended to set up a cron job to delete customized PDFs from the wp-content/uploads/waterwoo-pdf folder.

Amazon S3 Hosted Files

If using WooTheme’s S3 plugin, you must create a SHORTCODE to use as the product file path. Documentation for how to set up a bucket, S3 file, and shortcode are here.

A shortcode will look like this:

[amazon_s3 bucket=MyBucketName object=MyFileName.ext]

Noted June 2018: WooCommerce’s Amazon S3 plugin does not work to deliver files if your bucket name is a domain name (e.g. “mydomain.com”) or has a period (“.”), dash (“-“), or space in it.

Dropbox Hosted Files

To set up WaterWoo to work with Dropbox, you will need the separate Woocommerce Dropbox Plugin. Please follow its installation instructions to set it up. Also please contact its developers with any questions about its setup. Once that plugin is set up correctly, you will be able to easily select PDF files from Dropbox in your product editor.