Pages

Saturday, November 14, 2015

How to install the multi-platform PDF pop-up window on your Moodle 2.9.x/3.0 site.

Pop up! Source: Pixabay,
License: CC0 Public Domain;
See https://goo.gl/lAIF8x


Welcome to my Dummies' Guide for the Complete Dummy!

This guide will show you how to enable your Moodle 2.9 site so that if you click on a PDF file resource, a lighbox-like pop-up window will open. I made mention of this 'innovation' here.

A dumbed-down version of this guide is called the Idiot's Guide. But I haven't gotten down to doing it yet because I'm not a complete idiot. Yet.


I crafted this Guide because I am afraid that three months from now I might forget all the steps. Thus the Dummy is I. This guide is insanely populated with screenshots because it is a step-by-step guide for, like I said, Dummies.

A Dummies' Guide should be simple enough for any 'Dummy' to follow. All you need to do is to follow the steps and in the end you will be rewarded. I will hold your hand all the way through.

Learning Outcomes
At the end of this Guide, you will be able to
  • install the PDF pop-up on your Moodle 2.9.x/3.0 site using one of these themes: evolve-D, BCU and Academi. Disclaimer: if you are using a different theme, I cannot guarantee that it work on your theme. I tried to get it to work on Essential, More and Clean themes. I failed. Maybe you can succeed where I failed.
  • to experience the joy of seeing your students open up PDF files as a pop-up window on Moodle, on every platform and device known to man. After this you can sit back, relax and watch Netflix.
  • to see a PDF, Text and ODF (Writer, Presentation, Calc) file open on multiple platforms in the same and consistent way. Check out the Slideshare presentation below. Drool.
Slideshare Presentation (screenshots of Multi-platform pop-ups)



Want to know more? Read on!


Me showing the FancyBox PDF pop-up.  Moodle 2.9 site. iPhone5 smartphone.
The Moodle theme I used is evolve-D by 
Chris Kenniburg.


Before you proceed further, please watch this Slideshare presentation. I presented it on iMoot Mini 2015 on Friday, November 6th 2015. Slides 32 to 40 are the ones that will give you the BIG PICTURE of how I enable my site to do PDF and ODF pop-ups. Pay attention to those slides. But enjoy the full presentation of course! :-)

iMoot Mini 2015 Presentation by Frankie Kam




Introduction and Prequisites

I've just created a new installation of Moodle 2.9.2+ (Build: 20151031).
It's at http://www.moodurian.com/durian

So in order to do this guide, you will need the following:
(a) A working Moodle 2.x site;
(b) FTP client like FileZilla  for uploading and renaming files. Alternatively, CPanel with File Manager will also do;
(c) the Admin username and password of either the FTP or CPanel accounts of your Moodle site;
(c) A text-editor like Notepad++ to edit the source file(s)
(d) About 20 to 30 minutes of your time.

Let's roll!


Step 1: Download PDF.js libraryfrom https://www.dropbox.com/s/pp6o3ahs147kh53/pdf.js-gh-pages.zip?dl=0

PDF.js or pdf.js is a JavaScript library intended to render PDF files using the HTML5 Canvas for a safer and web standards compliant web browser rendering of PDF file. The project was launched in 2011 and is led by the Mozilla Foundation. I use it to load up a PDF file inside a Fancybox.

When you click the link you will see this screen.

Click the Download button. After you extract the download pdf.js-gh-pages.zip file you should see this folder structure:



Alternatively, you can download the latest copy from:
https://mozilla.github.io/pdf.js/getting_started/#download

When you click the link you will see this screen.


Choose the link that says "Stable". If you are feeling adventurous, then try the Beta link. The Stable zip file is around 3 Megabytes. After extracting the zip file you should see this folder structure:


IMPORTANT!
You will later RENAME the folder pdfjs-1.1.366-dist to  pdf.js-gh-pages (see end of Step 5)!


Step 2: Download the ViewerJS code from the direct link http://viewerjs.org/releases/viewerjs-0.5.8.zip or by going to http://viewerjs.org/getit/ and clicking on the viewerjs-0.5.8.zip download button.

ViewerJS is pretty versatile document viewer that resides on your web server itself. The purpose of ViewerJS is to load OpenDocument files within a Fancybox. You can actually use ViewerJS to also load your PDF files, but I prefer to use PDF.js for that purpose.


After extracting the zip file you should see this folder structure:



Step 3: Download my 'Secret Recipe' code from https://www.dropbox.com/s/6coxzlaet21y4uh/moodle-hack-fancy-box.zip?dl=0

The 'Secret Recipe' code is a potpourri of Fancybox images, Javascript and CSS files. FancyBox is a tool that offers a nice and elegant way to add zooming functionality for images, html content and multi-media on your webpages. It is built on the top of jQuery and can be customised

The code is from my Dropbox account. You'll need a Dropbox account to download the code from the link above. The zip file is around 68 Kilobytes(!). After extracting the file you should see this folder structure:




Step 4: FTP and upload the PDF.js library I.e., the pdf.js-gh-pages or the pdfjs-1.1.366-dist folder from Step 1 (and its contents) to your Moodle main folder

FTP to your Moodle site and navigate to the your Moodle main folder, i.e., /public_html/yourmoodle. In my example, all my Moodle files and folders are inside /public_html/durian. So for me, durian is my yourmoodle folder.

Select either the pdf.js-gh-pages folder or the pdfjs-1.1.366-dist folder and upload it to your main Moodle folder. The folder contains 362 files. So it will take a while to upload, depending on your Internet speed.

For the rest of this Guide, I will use the pdfjs-1.1.366-dist folder as the example. It applies the same to if you had downloaded the pdf.js-gh-pages folder.

Alternatively, if you have CPanel access, you can upload the folder as a compressed Zipped file and then extract it as the  folder pdfjs-1.1.366-dist inside /public_html/yourmoodle, which will be much faster compared to doing an FTP upload. Otherwise, if you have the time, then it is simpler and easier to just do an FTP upload.

In my example,

Before:

After:


IMPORTANT!
You MUST NOW RENAME the folder pdfjs-1.1.366-dist to  pdf.js-gh-pages



Step 5: FTP and upload the ViewerJS folderfrom Step 2 (and its contents) to your Moodle main folder

FTP to your Moodle site and navigate to the your Moodle main folder, i.e., /public_html/yourmoodle. In my example, all my Moodle files and folders are inside /public_html/durian.

Select the ViewerJS  folder and upload it to your main Moodle folder, i.e., /public_html/yourmoodle.

Alternatively, if you have CPanel access, you can upload the folder as a compressed Zipped file and then extract it as the  folder ViewerJS inside /public_html/yourmoodle, which will be much faster compared to doing an FTP upload.

In my example,

Before:

After:

Step 6: Install one of these Moodle themes
(if you haven't already done so)

Like so:



and


log into Moodle.org and navigate to the Evolve-D theme's plugin page.


Click the Install Now button and continue on with the series of buttons, links and screens until the theme is installed.


Step 7: Copy the Fancybox CSS file
from the source to destination subfolder


Copy moodle-hack-fancy-box\style\jquery.fancybox.css file into the /public_html/yourmoodle/theme/evolved/style subfolder

You should see this:


Simple and painless so far.


Step 8: Create a sub-folder named javascript inside /public_html/yourmoodle/theme/evolved/

If the subfolder /public_html/yourmoodle/theme/evolved/javascript already exists, then Step 6 can be skipped.


Step 9: Copy the following Javascript files
from the source to destination subfolder


Copy moodle-hack-fancy-box\javascript\jquery.fancybox.js file into the /public_html/yourmoodle/theme/evolved/javascript subfolder

Copy moodle-hack-fancy-box\javascript\jquery.fancybox-media.js file into the /public_html/yourmoodle/theme/evolved/javascript subfolder

You should see this:


So far this is easy right? Now let's edit a core theme file.


Step 10: Copy the pixpdf folder
from Step 3 into the /theme/evolved folder


Before:

After:


Step 11: Edit the config.php file
of your theme (add the CSS filename)


FTP to your Moodle site and navigate to the /public_html/yourmoodle/theme/evolved folder.


Select the public_html/yourmoodle/theme/evolved/config.php file. You might want to download a copy and rename the downloaded copy to config_original.php or something memorable - just in case.

Search for the code $THEME-->sheets and edit the line where it appears. Specifically, insert the code , 'jquery.fancybox' after 'custom'. Like so:

Before:

After:

Notice that I added the code 'jquery.fancybox' to the array list inside line 28 of config.php.

Save the file and make sure the saved file is uploaded back into the public_html/moodle/theme/evolved/ folder.


Step 12: Add the Javascript filenames
to your config.php file


Add the code

$THEME->javascripts_footer =
   array('jquery.fancybox',
'jquery.fancybox-media');
inside the config.sys file. For example, 

Before:

After:

Save the config.php file.
If you have reached this far, well done. The last step is a core code hack. You're almost there. Go ahead, take a breather. Or take five (minutes break).


Step 13: Edit the /course/renderer.php file 

Note: this is a core code hack. Please be vigilant, exercise caution, and above all, BACKUP your original core file!

FTP to your Moodle site and navigate to the /public_html/yourmoodle/course folder.


Make a backup of your /public_html/yourmoodle/course/renderer.php file. In the example shown below, I have renamed it to /public_html/yourmoodle/course/renderer_original.php


Do you notice the file named Inside_the_course_folder_renderer.php inside the folder \Downloads\moodle-hack-fancy-box ? It is a Moodle 2.9.2 file. If both renderer.php files are the same Moodle version, then you can just replace the original /public_html/yourmoodle/course/renderer.php file with the contents of the Inside_the_course_folder_renderer.php file.

In the example shown below, I first upload the modified file to /public_html/yourmoodle/course.


Then I rename the modified file to /public_html/yourmoodle/course/renderer.php.


The difference between the two renderer.php files is just the function named public function course_section_cm_name(...). This can be clearly seen in this diffchecker.com link: https://www.diffchecker.com/iqhbdysl


Step 14: Enable enable OpenDocument Format (ODF)
files to pop-up 


The last thing you need to do is to edit the /public_html/yourmoodle/course/renderer.php file like so:

Before:

After:

Rename that teach folder to your main Moodle folder's name. In my example, my main Moodle folder's name is durian.

If you do this correctly, the ViewerJS PDF viewer will be called whenever you click on an Open Document / Open Office / Libre Office file. Specifically, a Writer, Calc or Impress file that has been dragged-and-dropped into the course page, with the "Display" option set to the default "Automatic".



Step 15: Adding a Loader/Spinner to the ViewerJS viewer

The purpose of a loader/spinner image is two-fold:
(1) To tell the user that something is going on (loading is progress)
(2) To allow the admin to brand the company or product by using a customised logo as the spinner image.


How did I add a customised spinner to the ViewerJS?

The folder ViewerJS contains a file named index.html. The code to add a custom spinner gif image is found inside this index.html file.
To know where to put it, please download the zip file from: https://goo.gl/Fw837Y
This zip file contains three files:
  • index.html 
  • index_original.html
  • spinner.gif

The file named index.html is the modified file with the GIF spinner code inside it, while the file named index_original.html is obviously the original index.html minus the code that adds the spinner gif. The file named spinner.gif is an animated GIF file (rubik's cube).

To understand fully what to do, you can also go to: https://github.com/kogmbh/ViewerJS/issues/96 and you will see that I have solved the problem of the stock ViewerJS not having a spinner/loader gif. I reproduce the crux of the issue solved:


To see the difference between the two files index.html and index_original.html, click on this diffchecker.com link:
https://www.diffchecker.com/ch6uchil

I reproduce the result of the diffchecker link by showing you this screen snippet:
  • The red rectangle contains the code of the modified index.html
  • The greed rectangle contains the code of the original, unmodified index.html.
  • The red and green highlighted code are the differences between the two files. All other code are exactly the same! The differences are as clear as crystal.

Here's the critical line of code:
url(images/spinner.gif);background-repeat: no-repeat;background-position: center; }#canvasContainer.slideshow

It tells the browser to load the spinner.gif in the background of the ViewerJS window. The position of the gif file is specified as "center".

The yellow background code is the difference of code between the red and green rectangular sections.

So, to add a spinner image to the ViewerJS,
(a) you can make use of my modified index.html, simply upload it to
/public_html/yourmoodle/ViewerJS overwriting the original index.html file.
(b) Upload the spinner.gif file to your /public_html/yourmoodle/ViewerJS/images folder. You can replace it with an animated loader/spinner image file of your own choice.

If you want to use my gif file, here it is:



Step 16: Modify the Loader/Spinner of the PDF.js viewer
If you wish to change the default spinner of PDF.js, it is very easy. Look for the file named /public_html/yourmoodle/pdf.js-gh-pages/web/viewer.css. The CSS file contains this line of code (around line#150):


Here's the original loading-icon.gif file which is located in: /public_html/yourmoodle/pdf.js-gh-pages/web/images/loading-icon.gif 



So if you want to replace it, just rename the Rubik's Cube gif as loading-icon.gif and upload it to /public_html/yourmoodle/pdf.js-gh-pages/web/images/


Simple!

By the way, the Rubik's cube above is a slightly smaller version of the first one shown at Step 15.


Step 17: Test your Site
The proof of the pudding is in the eating!

You should now enjoy the fruit of you labour by going to your Moodle site and clicking on the course that has its theme set to Evolve-D. Remember to use this theme as per this Guide to test the pop-ups.

Go to my test Moodle 2.9.2+ sites at http://www.moodurian.com/durian/course/view.php?id=2 and login as:
Username: sippycup
Password: Happy_golucky123

AND

http://cefl4u.org/teach/course/view.php?id=13
Username: sippycup
Password: Happy_golucky123


Click on the PDF file on the course page.

Phew, after all that effort, it works! If it didn't work for you, check all the steps above. Fine-tooth comb every instruction step. Did you miss out anything?

Also try to clear your Moodle cache by going to Site Administration | Development | Purge all caches.

Here's the PowerPoint file that has been saved as an ODP file:


Very nice. That's it!

If you managed to get it to work on your site, I would love to hear from you.
:-)

Regards
Frankie Kam

Postscript - 16th November 2015
I have modified both /course/renderer.php and added some code to /theme/evolved/style/jquery.fancybox.css so that now you can also pop-up OpenDocument Format (*.ods, *.odp, *.odt) and text (*.txt) files inside a Fancybox. Click on the links above to download the latest two files with the changes made.

Postscript - 21st November 2015
I used this Moodle.org forum post/thread and Shadowbox to enable the PDF popup for Essential and Pioneer themes! Many thanks to Mary Evans for guiding David Choi through the steps to enable Shadowbox Javascript library in Moodle.

Proof1: Essential theme



Proof2: Pioneer theme


This is a subject for a new blog post on the subject. For another day!

If you like this post or site
a small donation would be nice but would last only a day,
otherwise leaving a comment (or a compliment) below will last me a month!

Ratings and Recommendations by outbrain