WordPress PDF Light Viewer Plugin v1.3.19
& PRO Addon v0.1.4
Documentation

What did you get?

About

Thank you for usign the WordPress PDF Light Viewer Plugin.

This plugin gives you an ability to embed PDF files to your Wordpress sites.

You could add unlimited amount of PDF of any size without performance issues.

Added PDF could be embedded as flipbooks on frontend.

PRO Addon is not required but it adds some useful features (marked with PRO here) which you can check in this documentation or on the Addon's page.

Please note that PRO Addon is not standalone plugin and it requires PDF Light Viewer free plugin.

Features

  • Unlimited PDF files.
  • Unlimited PDF file size without site performance issues.
  • Turn.js flipbook integrated.
  • Dashboard flipbook preview.
  • Slider thumbnails navigation integrated.
  • Lazy loading pages integrated.
  • Pages zoom feature.
  • Pages fulscreen feature (for modern browsers).
  • s2member compatible.
  • Developer-friendly.
  • Well-documented.
  • Fully translatable to any language using .po files.
  • Supports wordpress multisites
  • Responsive design
  • Clear default look
  • CLI integration
  • Bulk PDF Import
  • Downloading and per-page downloading

PRO Features

  • Single separate PDF page.
  • Regular Wordpress PDF Archive page with 2 templates.
  • One-page PDF Archive page with 2 templates.
  • PDF Archive page by shortcode on custom page or frontpage.
  • PDF Categories.
  • Simple PDF page search.
  • Document printing.
  • Per-page printing.
  • SEO friendly mode.

What next?

Check Installation section to know how to install the plugin.

Installation

How to install?

Installation steps

Regular installation

  1. Get the package Ok, you got the plugin package :)
  2. Upload plugin package with WordPress http://yoursite.com/wp-admin/plugin-install.php?tab=upload or WordPress Multisite http://yoursite.com/wp-admin/network/plugin-install.php?tab=upload
  3. Activate PDF Light Viewer Plugin on the WordPress Plugins page http://yoursite.com/wp-admin/plugins.php
  4. PRO Tip: Activate PDF Light Viewer Pro Addon on the WordPress Plugins page http://yoursite.com/wp-admin/plugins.php
  5. That's all! You can start from Quick start guide
  6. After plugin activation please go to plugin's settings on the page http://yoursite.com/wp-admin/options-general.php?page=pdf-light-viewer to Set Up the plugin.
  7. PRO Tip: Settings of the PRO functions are placed on the main plugin Settings page.

cPanel installation

  1. Upload plugin package through the cPanel File Manager to the /wp-content/plugins/
  2. Extract plugin package contents to the /wp-content/plugins/ folder
  3. Activate PDF Light Viewer Plugin on the WordPress Plugins page http://yoursite.com/wp-admin/plugins.php
  4. PRO Tip: Activate PDF Light Viewer Pro Addon on the WordPress Plugins page http://yoursite.com/wp-admin/plugins.php
  5. That's all! You can start from Quick start guide
  6. After plugin activation please go to plugin's settings on the page http://yoursite.com/wp-admin/options-general.php?page=pdf-light-viewer to Set Up the plugin.
  7. PRO Tip: Settings of the PRO functions are placed on the main plugin Settings page.

FTP installation

  1. Unpack the plugin package with any archiving tool, which supports ZIP file format
  2. Upload files folder to the /wp-content/plugins/ to the server with any FTP client application, for example FileZilla
  3. Activate PDF Light Viewer Plugin on the WordPress Plugins page http://yoursite.com/wp-admin/plugins.php
  4. PRO Tip: Activate PDF Light Viewer Pro Addon on the WordPress Plugins page http://yoursite.com/wp-admin/plugins.php
  5. That's all! You can start from Quick start guide
  6. After plugin activation please go to plugin's settings on the page http://yoursite.com/wp-admin/options-general.php?page=pdf-light-viewer to Set Up the plugin.
  7. PRO Tip: Settings of the PRO functions are placed on the main plugin Settings page.
More about WordPress Plugins Management

What next?

Check Quick start guide section to see quick examples of plugin's usage.

Quick start guide

How to hit the ground running?

First of all you need to check plugin requirements.

Requirements

  • PHP 5.3 or higher
  • ImageMagick PHP extension OR GraphicsMagick PHP extension
  • Imagick PECL library OR Gmagick PECL library
  • GhostScript support
  • Writable upload folder wp-content/uploads/pdf-light-viewer
  • (optional) WP CLI if you plan to use plugin from the CLI

PRO Requirements

  • PDF Light Viewer installed and activated
  • Specific version on PDF Light Viewer

After activation plugin will create new post type for PDF files. You'll see pointer notification near it's menu item.

Activation notifications

Also right after activation, plugin will check requirements and will notify you about checking results. If requirements are met, notification will show up and disappear.

But if some requirements are not met, you'll see constant error notification. Follow the link in the notification to see details on the settings page.

Error notification

You can find WordPress PDF Light Viewer Plugin settings page by following url address like this one http://yoursite.com/wp-admin/options-general.php?page=pdf-light-viewer

If some requirement is not met, you will see it on settings page

Requirements are not met

PRO Tip: Settings and requirements for PRO Addon could be found on the same page

PRO Requirements

ImageMagick/GraphicsMagick support

The ImageMagick/GraphicsMagick package and Imagick/Gmagick library are required for PDF Light Viewer plugin to work. Not supported in current context means that the Imagick library is not installed or turned off on the server. To make plugin work you will need to install it or to turn it on.

ImageMagick is the image manipulation library for PHP. ImageMagick is a server software and currently not included into the plugin.

To make it work, someone, you, your server administrator or your hosting provider, should install (or enable, if it's already installed) this software on your server. If your site is maintained by some administrator, he or she already knows how to install ImageMagick and Imagick libraries. Otherwise the installation could be done through cPanel in some cases and you could try to install it.

Sometimes your hosting provider could restrict installation of additional software. In this case you can contact them for further instructions and details.

To install ImageMagick manually please visit this installation guide.

GhostScript support

The GhostScript package is required for PDF Light Viewer plugin to work. To make plugin work you will need to install it on the server.

GhostScript is the application to work with PDF files. GhostScript is a server software and currently not included into the plugin.

To make it work, someone, you, your server administrator or your hosting provider, should install this software on your server. If your site is maintained by some administrator, he or she already knows how to install GhostScript.

To install GhostScript manually please visit this installation guide.

Big thanks to Alexander for this notice.

GhostScript is required for Imagick PDF Support. For cases, when you are sure that GhostScript is installed, but it was not detected by the plugin correctly you can disable this requirement in plugin's settings.

What next?

Check Set Up section to know more about plugin global settings.

Set up

Where to start?

Main Settings

You can find WordPress PDF Light Viewer Plugin settings, requirements and documentation on the page http://yoursite.com/wp-admin/options-general.php?page=pdf-light-viewer

In settings you can hide the new PDF post type from the admin menu. This is useful, when you uploaded PDF files not often and do not want to unnecessary item to take the space of the screen.

Settings

You can turn it on again at any moment.

Also in setting you can turn off checking of GhostScript installation for cases when plugin cannot recognize the version.

PRO Settings

Settings

You can show PDF single pages on your site. For this check options Make PDFs public available.

To show PDFs archive check Post type has archive option in addition to Make PDFs public available.

Change url slug for PDF pages in setting Public PDFs rewrite slug

Options Use custom post type archive template from plugin and Use custom post type single template from plugin may be unchecked if you want to customize Single and Archive page templates.

What next?

Check Usage section to know more about use cases.

Usage

How to use?

The process of publishing PDF files is the following:
  1. User uploads PDF document
  2. PDF document is parsed by the plugin
  3. User stays on the site until the document is parsed
  4. User adds the wordpress shortcode, produced by the plugin, to the page or post
  5. PRO User can open Single PDF page to have PDF flipbook there.
Importing PDF file

You can go to PDFs menu item to see the list of imported PDF files.

PDF Files in menu

If you just installed the plugin the list will be empty. Go ahead and import first PDF document by clicking Import PDF button.

Importing of PDF is similar to the creating regular WordPress post or page but there are some differences.

Importing PDF

You can specify the title for the PDF. It's for internal use only, it wouldn't be shown in the default shortcode.

PRO Tip: The title will be shown on Archive and Single pages.

You're available to change some importing options such as:

  • JPEG compression quality
  • JPEG resolution

Changing these options will affect importing process.

To import PDF file choose the file from the Media Library and check the checkbox Enable import

Click Publish to start the import.

Import scheduled

We moved the import process to the background, so you could continue to do other things on the site if needed.

The import process doesn't use the WP Cron functionality. It's triggered by browser's background (AJAX) call. We could not rely on WP Cron functionality because some servers (we faced that problem with Hostgator) doesn't allow loopback requests.

The import process will work from any admin interface page.

It will work until you leave the admin interface and will continue when you come back.

Anyway, please note, that import of large PDF files (50 pages and more) will take some time.

Also, please note, that import of large PDF files will take some server resources (memory usage, CPU time, etc.). Usage of these resources depends on PDF file size, number of pages, initial PDF resolution, etc.

That's why we separated the import process by pages.

Please, use carefully.

The import time depends on the server. Anyway, you can check import progress in notification at the top of the page, or on the PDF list page.

PDF List Page

After import, the first page will be set as featured image of the PDF file post.

PRO Tip: Featured image will be shown on PDF Archive page.

Re-importing PDF file

To re-import PDF file, choose the new file from the Media Library and check the checkbox Enable import

Click Update to start the import.

Please note, that all previously imported pages of this document will be deleted from the disk. This operation cannot be undone.

Updating PDF file

If you just need to change the name of the PDF file or some of the Output options, you leave the option Enable import unchecked. Without checking this checkbox import wouldn't be triggered.

Deleting PDF file

If you will permanently delete PDF file post, all previews will be also deleted.

Please note, that this operation cannot be undone.

Output Options

You can change different output options such as:

  • Hide thumbnail navigation
  • Force one-page layout - usually book will be shown in two-pages layout when the page is wider than 800px. This setting will force one-page layout always.
  • Max book width
  • Max book height
  • Limit book height by the viewport in fullscreen mode - plugin will try to fit the screen height
PRO Output Options

You can change different Output options such as:

  • Enable search engine optimization - in this case links of thumbnail navigation will open "real" pages with PDF text included in the invisible <noscript> tag for SEO.

Toolbar Search PRO

Please note, that SEO friendly mode and simple search will work only if PDF contains text and it was successfully parsed from the file during the import.

If you've imported PDFs in PDF Light Viewer plugin without PRO Addon, then you'll need to re-import those files to make SEO friendly mode and search functions work.

Toolbar Options

You can change different output options such as:

  • Allow download - download button to download the whole PDF document
  • Alternate download link - if not set, then "PDF File" will be used
  • Allow per-page download - separate pages could be downloaded
  • Per-page download format - you can choose JPEG or PDF
  • Hide fullscreen button
  • Disable page zoom - toggle mouse-over zoom function
  • Show toolbar next and previous page arrows
  • Show toolbar go to page control
  • Show page numbers
PRO Output Options

You can change different Toolbar options such as:

  • Enable search through the PDF - autocomplete ajax search of the text content of the PDF document
  • Allow document printing
  • Allow per-page printing

Toolbar Search PRO

Please note, that SEO friendly mode and simple search will work only if PDF contains text and it was successfully parsed from the file during the import.

If you've imported PDFs in PDF Light Viewer plugin without PRO Addon, then you'll need to re-import those files to make SEO friendly mode and search functions work.

Changing permissions

In the Permissions section you can add limits for different user roles for this file.

If you'll choose Anonymous user role and set limit to 3, then on the Front of the site anonymous users will see only first 3 pages of the PDF file.

Shortcodes

After import you can add PDF files with shortcodes anywhere in your post or page. You can copy shortcodes from PDFs list page or compose them manually.

PDF List Page

Preview

After import file you could preview your file exactly how it will be shown with help of shortcode on the frontend.

PDF List Page

Visual Composer

In case when you're using Visual Composer plugin, the better approach would be to map PDF Light Viewer shortcode.

Map Shortcode

After mapping you can go to the page, when you want to have your PDF document and insert it there like shown below:

Shortcode Select

Shortcode Set Up

What next?

Check Advanced Usage section to get full control on the plugin functionality and look and feel.

Advanced Usage

Are you developer?

So you're developer or maybe just want to know more about the plugin. We take care about you, no matter, whether you get our plugin from the client or bought it for your purposes. You don't need to change anything inside the plugin (at least we hope so).

You will have full control on the plugin right from other plugin, or theme, or whatever you use in your wordpress.

Code control

You can override any of plugins classes somewhere before the after_setup_theme action:

  • PdfLightViewer_Plugin - some main functions
  • PdfLightViewer_AssetsController - css and js assets including
  • PdfLightViewer_AdminController - admin functions
  • PdfLightViewer_FrontController - frontend functions
  • PdfLightViewer_PdfController - custom PDF post type and related functions

PRO Tip: PRO Addon has similar file structure and can be overrided in the similar way.

Templates control

You can create shortcode-pdf-light-viewer.php in your theme or copy it from templates folder to your theme folder to override all default plugin template for frontend.

PRO Tip: To override Archive, Single pages or even Printing view you could copy to your theme folder files archive-pdf_lv.php, single-pdf_lv.php or print-pdf_lv.php accordingly.

Plugin Output

Shortcode [pdf-light-viewer] as well as PdfLightViewer_FrontController::display_pdf_book($atts = array()) has following parameters:

  • id (required), this is ID of the PDF post, you can
  • template (optional), you can specify template name to override default. Template name can be any, that accepted by get_template_part() function.

You could call class method PdfLightViewer_FrontController::display_pdf_book($atts = array()) directly instead of using shortcode [pdf-light-viewer].

Shortcode [pdf-light-viewer-enqueue-assets] as well as PdfLightViewer_AssetsController::frontendEnqueue() has no parameters. It should be mainly used to enqueue assets when PDF flipbook shortcode is injected with widgets. It should be inserted before main PDF flipbook shortcode.

PRO Shortcode [pdf-light-viewer-archive] as well as PdfLightViewerPro_FrontController::display_pdf_archive($atts = array()) has following parameters:

  • title (optional), custom title above the archive
  • categories (optional), you can specify category slugs separated by commas "," - for example [pdf-light-viewer-archive categories="top,featured"].
  • template (optional), you can specify template name to override default. Available options are:
    • (empty or not set) - Material masonry (default)
    • masonry-full-thumbs - Masonry full thumbnails
    • one-page-with-list-nav - One page with list navigation
    • one-page-with-thumbs-nav - One page with thumbnails navigation
WordPress Hooks (actions and filters)
Filters:
  • Conditional assets filter
    • Filter: PDF_LIGHT_VIEWER_PLUGIN.':should_enqueue_frontend_assets'
    • Expected result: Boolean

      When true, the plugin will include assets even if it cannot detect PDF Light viewer shortcodes.

    • Example (compatible with php 5.3+):
      add_filter(PDF_LIGHT_VIEWER_PLUGIN.':should_enqueue_frontend_assets', function() {
      	return true; // add your custom logic here
      });
      
    • Conditions: Should be added before wp_enqueue_scripts hook is triggered.
CLI usage

You can work with plugin from command line interface. PDF Light Viewer integrated with great WP CLI, thus the plugin requires WP CLI to work in command line.

Command wp pdf-light-viewer has following subcommands:

  • bulk-import - Bulk PDF import

    Options:

    • source-dir required, source directory to import PDF files
    • jpeg-compression-quality optional, jpeg compression quality, default 60
    • jpeg-resolution optional, jpeg resolution, default 300
    • post-status optional, PDF post status, default "draft"
    • import-pdf-file flag, if set then import PDF file to Wordpress media library

    Example:

    $ cd /path/to/your/wordpress
    $ wp pdf-light-viewer bulk-import --source-dir="/path/to/pdfs" --jpeg-compression-quality=60 --jpeg-resolution=300 --post-status=publish --import-pdf-file
    

    or you can specify wordpress' path via option:

    $ wp pdf-light-viewer bulk-import --source-dir="/path/to/pdfs" --jpeg-compression-quality=60 --jpeg-resolution=300 --post-status=publish --import-pdf-file --path="/path/to/your/wordpress"

What next?

Check Support section to get in touch with our support team.

Support

Need support?

To contact us please use support forum at http://support.wp.teamlead.pw or email support@teamlead.pw

We will appreciate your votes - Vote for us!.

PDF Light Viewer Pro Addon can be purchased on Codecanyon separately.

Also please find us on CodeCanyon: http://codecanyon.net/user/teamlead-power/portfolio

Knowledge Base

Credits

Sources used

Changelog

PDF Light Viewer

1.3.19 - 2017-09-11

  • First page thumbnail bug fix

1.3.18 - 2017-07-27

  • PDF support improvement

1.3.17 - 2017-03-29

  • Private PDFs fix

1.3.16 - 2017-02-10

  • Fix for ghostscript usage during the import (for wrong resolution issue)
  • Setting to force two-pages layout for some screen sizes
  • Enable/disable Zoom interactively
  • Zoom magnify option

1.3.15 - 2017-01-19

  • Stop import possibility
  • Assets enqueue improvement
  • Added French translation (R. Valentin)

1.3.14 - 2016-11-25

  • Add setting to turn on/off url flipbook navigation
  • JS function to recalculate sizes

1.3.13 - 2016-11-18

  • fix PHP 5.3 compatibility

1.3.12 - 2016-11-16

  • Added shortcode to enqueue assets in widgets

1.3.11 - 2016-11-11

  • Added assets limit conditions and filter
  • GraphicsMagick: Low quality for resulting images fix
  • Improve page images preloading

1.3.10 - 2016-10-03

  • Option to adjust result images size
  • Fixed bug with resulting image quality
  • Mobile styles improvements
  • Fixed php error when server has no Imagick/Gmagick
  • Fixed javascript bug in IE
  • Changed file upload field to prevent url pasting

1.3.9 - 2016-09-11

  • fix PHP 5.3 compatibility
  • preload page images

1.3.8 - 2016-09-02

  • Improved and fixed Gmagick support
  • Added control for imagemagick/graphicsmagick switching
  • Improved single page PDF download
  • Added maximum viewer height setting
  • Added go to page functionality

1.3.7 - 2016-08-25

  • Post including logic improved
  • Settings page help small improvements
  • Smallfix for function type
  • Documentation update

1.3.6 - 2016-08-19

  • Make password protection work
  • Single page PDF download
  • Fixing minor php errors

1.3.5 - 2016-07-31

  • Adjustable viewer height

1.3.4 - 2016-07-08

  • CLI import fix

1.3.3 - 2016-06-24

  • CMB2 compatibility pull request merged
  • toolbar fix
  • pre-page download fix
  • fullscreen fix

1.3.2 - 2016-06-22

  • per page download in toolbar
  • page numbers bugfixing

1.3.1 - 2016-06-21

  • GraphicsMagick alternative support
  • Page numbers in toolbar
  • Control arrows in toolbar

1.3.0 - 2016-06-07

  • CMB to CMB2 dependency upgrade
  • imagetragick notification added
  • hide button for welcome notification
  • templates structure improvements
  • added import of only specific pages
  • per-page downloading

1.2.7 - 2016-04-27

  • added maximum book width setting
  • fix PHP 5.3 compatibility
  • improved fullscreen mode

1.2.6 - 2016-04-22

  • Simple Line Icons conflict fix
  • fix for compatibility with Magazon and other themes
  • Smart Manager compatibility fix
  • Mailpoet compatibility

1.2.5 - 2016-04-14

  • improve colors and/or colorspaces of resulting images

1.2.4 - 2016-03-21

  • option to display with a single page layout only
  • hide top toolbar when there are no icons
  • categories for PDFs
  • additional template to display thumbnail carousel at the top instead of the bottom
  • enhance full screen function in Chrome and IE

1.2.3 - 2016-01-20

  • integration with WP CLI
  • added CLI command bulk-import
  • fixed missing font-awesome css
  • icons compatibility fix

1.2.2 - 2015-12-25

  • fixing issue with 404 links in pagination

1.2.1 - 2015-12-18

  • bugfixing pro addon compatibility
  • design improvements

1.2.0 - 2015-12-14

  • PHP 5.3 is now required instead of PHP 5.2
  • Design improvements
  • Changed icon set from FontAwesome to Simple Line Icons
  • Fixed admin notifications handling
  • Refactoring, improved code logic
  • Added compatibility with PRO Addon

1.1.7 - 2015-12-05

  • Fixed bug when 2nd page in a 2-page pdf not displayed in thumbnails
  • Pages limit bug
  • Fixed typos

1.1.6 - 2015-11-22

  • Improvements for lazy loading pages
  • Enabled zoom for fullscreen mode
  • Improvements to detect GhosScript installation on Unix-like systems
  • Improvements for settings page

1.1.5 - 2015-09-03

  • Fixes for compability with themes/plugins which are using humanmade/Custom-Meta-Boxes

1.1.4 - 2015-09-03

  • Fixed bug for metaboxes on Import page (when Import page shows only title)

1.1.3 - 2015-08-04

  • Added responsiveness for tablet and phones
  • Improved fullscreen mode
  • Hiding fullscreen button for browsers without Fullscreen API support
  • Fixing lazyload issues - thanks to Amit for reporting the issue
  • Some interface improvements - thanks to zipzit
  • BX Slider wrong path #3 - fixed
  • pdf-light-viewer template is not functional from user's theme. #5 - fixed

1.1.1-1.1.2 - 2015-07-15

  • Added information about GhostScript to the documentation - thanks to Alexander
  • Improved requirements section

1.1.0 - 2015-06-02

  • Improved CMYK PDF import
  • Improved admin import status messages
  • Added landscape PDF support
  • Fixed some bugs with images sizing
  • Increased default image sizes
  • Added page zoom for flipbooks
  • Added compability for 2 or more instances of plugin on the same page
  • Added options to disable zoom and fullscreen
  • Updated client side libraries

1.0.1 - 2015-01-14

  • Fixed PHP errors
  • Added docs explanation for Visual Composer How-To and "Imagick is not supported" requirement error

1.0.0

  • The plugin released

PDF Light Viewer Pro Addon

0.1.4 - 2016-09-02

  • Main plugin 1.3.8 support
  • Imrpoved one-page layouts navigation

0.1.3 - 2016-08-25

  • New one page archive layout with categories list navigation
  • New one page archive layout with categories thumbs navigation
  • Categories Images plugin integration

0.1.2 - 2016-07-08

  • PDF text import improvement with Ghostscript

0.1.1 - 2016-06-22

  • category pages
  • category menu

0.1.0 - 2016-06-07

  • per-page printing
  • archive view with full PDF thumbnails

0.0.7 - 2016-04-28

  • php 5.3 compatibility fix

0.0.6 - 2016-04-22

  • archive shortcode categories parameter

0.0.5 - 2016-04-06

  • archive template view fix

0.0.4 - 2016-01-28

  • php 5.3 compatibility fix

0.0.3 - 2016-01-25

  • added shortcode to display PDF archive on single post/page

0.0.2 - 2015-12-18

  • pdf printing bugfixing
  • archive page bugfixing and improvements
  • design improvements

0.0.1 - 2015-12-14

  • Added printing function
  • Added simple search
  • Added PDF text import for SEO
  • Added PDF Archive page
  • Added PDF Single page

Authors

Contributors