PDF Importer installation

Since the release of SLOODLE 1.0, the SLOODLE Presenter has provided a PDF importer plugin. The purpose of the plugin is to allow the user to upload a PDF file, which will then be automatically converted into a slideshow of images. Unfortunately, most webservers do not support it directly.

System Requirements

You will need the following programs installed on your webserver in order to use the PDF Importer:

• ImageMagick
• GhostScript

Optional:

• MagickWand

Having the MagickWand extension is not always necessary, but it makes it easier and more reliable for the importer to find and use ImageMagick. If it is not installed (or if it cannot be loaded dynamically) then the importer will try to find and execute the ImageMagick 'convert' program on its own.

Installation Requirements You will need to have administrator privileges on the server to install necessary components. This is not the same as being a Moodle administrator. You may need ask your web-host or the system/network administrator at your institution to do this for you.

Using the Importer

Add a "Presenter" activity to your Moodle course, and click the "Import Slides" tab at the top right. Underneath "PDF Importer", it will display "Incompatible" if something does not seem to work. If you are using SLOODLE version 1.0.2 or later then you will be able to hover the mouse over it to see a summary of what is wrong.

To use the importer, click on "PDF Importer" and use the form to upload and convert a PDF file. It may takes several seconds, depending on the size of the PDF file. If it worked then you will be able to view the pages of the PDF file as image slides in the presentation. An error message will be displayed otherwise.

Setup

If your server has ImageMagick, GhostScript, and MagickWand installed already, then you are probably ready to use the PDF Importer immediately. No further setup should be required. Otherwise, you will need to install the following components (preferably in this order):

How do I install ImageMagick?

The simplest way of installing ImageMagick is usually to download a "binary release" from their website. Select the appropriate release for your operating system:

• Windows
• Mac OS
• Unix/Linux

Package manager (Linux)

If you are running a Linux webserver, then you may prefer to obtain ImageMagick using package management tools such as Yum. The procedure will be different depending on your operating system and other factors, but a typical shell command might look like this:

yum install ImageMagick

How do I install GhostScript?

You can get "binary releases" of GhostScript from their SourceForge site. Make sure you download the latest version for your operating system:

• GhostScript

Package manager (Linux)

As with ImageMagick, you can usually obtain GhostScript through a package manager on Linux. A typical command might look like this:

yum install GhostScript

How do I install MagickWand?

The MagickWand extension is often much more complicated to install than the other parts, but you can usually omit it if necessary. See the section below on "I can't install MagickWand" for more information on using the PDF importer without it.

It is recommended that you install it if possible though. For non-expert users, the easiest approach is often to make sure MagickWand is included when you install PHP. For more information, visit the MagickWand website.

I can't install MagickWand

If you can't install MagickWand, but you have ImageMagick and GhostScript installed, then the PDF Importer may work anyway. Try using it to find out. If it is incompatible, then it will probably be because the importer could not auto-detect the location of the ImageMagick 'convert' program. You will need to find the location of the program, and tell the PDF Importer where it is.

Check the sections below to help you find the complete 'path' to your convert program. When you have done that, you need to edit a file in the SLOODLE module. It is called "sloodle/plugin/presenter/pdfimporter.php". Near the top, you should see a line like this:

$IMAGICK_CONVERT_PATH = '/usr/bin/convert';

Replace '/usr/bin/convert' with the path to your convert program, but remember to keep single quotation marks in. It is recommended that you use only forward slashes (/) rather than backslashes, even if you are on a Windows computer. Make sure you do not leave a slash on the end of the path you specify.

Linux/Unix

If you are on a Linux (or similar) system, then the 'convert' program will usually be in a common binary ('bin') folder somewhere. For example, common paths are:

• /usr/bin/convert
• /usr/local/bin/convert

If you have shell (command line) access to your server, then you could try typing in "whereis convert". That will suggest some paths which you could try. However, it is quite common for webserver administrators to deny access to executable files. If you cannot find the convert program, then speak to your server administrator.

Windows

The ImageMagick programs will usually be installed into your "Program Files" folder, although it could have been installed directly to the hard disk. Your path will often look something like this:

• C:/Program Files/ImageMagick-6.5.7-Q16/convert.exe
• C:/ImageMagick-6.5.7-Q16/convert.exe

Please note that the version information ("6.5.7-Q16") may be different, but the rest of the information should be the same. Please remember to use forward slashes (/) in your path, instead of backslashes (\).

Mac

Sorry, I have never used a Mac so I have no idea! I suspect it will be somewhat similar to Linux/Unix though.

Troubleshooting

The plugin says "Incompatible", but I don't know why

Currently, the plugin does not give any indication of why it is incompatible, or how you can fix it. Hopefully this will be improved as of SLOODLE v1.0.2. The following list shows the most common reasons why it will be incompatible:

1. The 'convert' program could not be found
2. The 'convert' program failed to execute
3. ImageMagick is not installed
4. GhostScript is not installed

Please note that the ideal solution to problems 1 and 2 is to use the MagickWand extension for PHP (see How do I install MagickWand?). If that is not possible, then see the information below.

The 'convert' program could not be found

This problem occurs when the plugin cannot auto-detect ImageMagick on the server. This can often be because ImageMagick is installed in an unexpected location, so you will need to tell the plugin to find it. Follow the instructions for "I can't install MagickWand".

If that does not work, then it is possible ImageMagick is not installed. See the instructions for "How do I install ImageMagick?".

If ImageMagick is definitely installed but the plugin still cannot access it, then there may be a permissions problem on your server. PHP needs to be able to execute programs on the server, which means "safe mode" should be disabled. It also requires that the webserver program (such as Apache) has access to the ImageMagick 'convert' program. Granting the program access to it can be complex -- consult your operating system documentation for more details.

The 'convert' program failed to execute

When the plugin attempts to use the 'convert' program, there are several things which can go wrong. An easy mistake is forgetting to install GhostScript. See "How do I install GhostScript?" for more information.

Windows users: some versions of Windows have a totally unrelated program called 'convert'. It can get executed instead of the ImageMagick program, in which case you need to tell the plugin explicitly where to find the ImageMagick installation. Follow the instructions for "I can't install MagickWand".

If you had to specify the path to 'convert' explicitly then it is possible that you typed the wrong path.

Please also make sure you are using the latest versions of ImageMagick and GhostScript.

ImageMagick is not installed

You need ImageMagick installed on the server to use this plugin. See: How do I install ImageMagick?

GhostScript is not installed

You need GhostScript installed on the server to use this plugin. See: How do I install GhostScript?