How To Stand Out From The Crowd Using Paper.js With WordPress
Do you want to draw, paint and animate your WordPress page to create something unique and legitimately cool? Haven’t you always secretly wanted jellyfish swimming on your site, for example?
Who hasn’t!
Well – today is your lucky day because we’re going to be covering Paper.js, the brilliant javascript library which makes sites like patatap and paperoids possible.
If you have used Paper.js before and only want to find out how to integrate Paper.js with WordPress, feel free to skip the intro!
Table of Contents:
What is Paper.js?
What can I do with Paper.js and who is it for?
How to install Paper.js on my website?
How to set up Paper.js for WordPress?
What is Paper.js?
Paper.js is a javascript framework that lets you do prodigious things with graphics scripting. It is a self-proclaimed Swiss Army Knife of Vector Graphics Scripting, loved by both designers and developers alike.
Paper.js is an open source vector graphics scripting framework that runs on top of the HTML5 Canvas. It offers a clean Scene Graph / Document Object Model and a lot of powerful functionality to create and work with vector graphics and bezier curves, all neatly wrapped up in a well designed, consistent and clean programming interface.
Paper.js is based on and largely compatible with Scriptographer, a scripting environment for Adobe Illustrator with an active community of scripters and more than 10 years of development.
Paper.js is easy to learn for beginners and has lots to master for intermediate and advanced users.
It’s an easy way to make your website more fun and a fun way to make your website easier on the eyes.
Let’s put it this way: if jQuery is javascript on steroids, Paper.js is javascript on mushrooms – that’s where all the creativity comes from.
Basic Concepts: Canvas and Paperscript
A Canvas is an HTML5 element that literally acts as a canvas. I know, right! It is a container for graphics. You must use the script to actually draw the graphics on it. By default, the <canvas> element has neither content nor borders.
If you look closer at the Paper.js files or at the example below, you will see that instead of “text/javascript” we have “text/paperscript”.
Paperscript is a domain specific language made specifically for Paper.js, so it won’t work unless Paper.js is included.
What can I do with Paper.js and who is it for?
In Paper.js you can easily draw paths and shapes in any color and size. You can create items, objects, rasters, interactive tools, and layers. You can animate items, add mathematical operations and even create your own games. In short, what you can do in Paper.js is really only limited by your creativity and imagination.
Basic features of Paper.js:
Document Object Module
Creating paths and segments
Animation
Mouse and keyboard interaction
SVG import and export
Raster images and color averaging
Vector geometry
Mathematical operations
Object conversion
Note that in this tutorial I do not aim to explain every property and feature of Paper.js. I will focus on setting up Paper.js in WordPress. If you want to learn more about the functionality and the specific features of Paper.js, you can find great tutorials on their official site.
Also, have in mind that Paper.js is a javascript framework. You could technically do all the same things in vanilla javascript, but it would take you lines and lines of code.
Those familiar with both javascript and vector drawing apps like Adobe Illustrator will find Paper.js very intuitive and are most likely to profit from it the most. You can create paths in Paper.js similarily to how you would draw them in Illustrator. Of course, basic javascript knowledge is required.
How to install Paper.js on my website?
If you have Node or Bower, you can use npm install paper or bower install paper commands. Otherwise, to include Paper.js on your website you first have to download it from their official site at http://paperjs.org/download/.
Unzip the downloaded file inside your project’s folder (ie. in assets).
Add the following scripts inside the head of your HTML file:
Don’t forget to add the canvas element in your body – everything you have done in paperscript will only be visible on a canvas.
You don’t have to write your script in the head of your HTML – you can also create a separate paperscript file and add it to your HTML like this:
How to add Paper.js to WordPress?
In order to complete this tutorial and add the awesome functionality of Paper.js to your WordPress site, you must have access to your cpanel and file manager. OK? Cool, let’s go!
STEP 1: Create a child theme
You can create your child theme manually. I am lazy so I’m using a Child theme generator plugin (you can delete the plugin right after you create your child theme). In this tutorial, I’ll be using Astra theme as a parent for my child theme.
STEP 2: Download the latest version of Paper.js
Download the latest version here http://paperjs.org/download/
Unzip the downloaded file and open “dist” folder. There you will find paper-core and paper-full javascript files. I will be using paper-full-min.js because it’s a bit lighter than paper-full.js.
STEP 3: Upload the paper-full.min.js file into your Child Theme folder via File Manager
This is pretty straightforward, I hope. The location of my child theme is /wp-content/themes/astra-child/
STEP 4: Enqueue the paper-full.min.js script to your page
Let’s add javascript to our WordPress site the right way, with enqueueing.
We’re still in the File Manager. Go to your child theme and open a functions.php file. You’re encouraged to backup your functions.php before altering it. Copy the following code into the functions.php.file.
This script enqueues a paper.js library. “enqueue_paper” is just a name that I gave to this function. It can be anything, but you have to call for it later by the same exact name (handle).
Note that this code will enqueue the paper-full.min.js script to your whole WordPress site. Check the console – if it doesn’t show an error, it is enqueued properly. You can even add a console.log(“connected”) or alert(“connected”) in the paper-full.min.js file to make sure everything runs smoothly.
I wanted to add Paper.js script to a specific page so I had to add the conditional tags to my function.
Like this:
In this case, 148 is the ID of my page. Yours will probably be different. The quickest way to see your post’s or page’s ID is to check its URL while you’re editing it in the backend. For example, my page had this URL:
mydomain.com/wp-admin/post.php?post=148&action=edit
The numbers after post= are the ID of your page.
The Theory Behind Enqueuing
In case you didn’t check out this post, here’s how enqueuing works. Instead of adding your script in the header or footer of your HTML file, in WordPress, you have to use wp_enqueue_script. This is to ensure that various scripts don’t mix up and break the site.
So, the wp_enqueue_script function registers and enqueues scripts. Let’s dissect it:
wp_enqueue_script( $handle, $source, $dependencies, $version, $in_footer );
$handle is just a name – a unique identifier with which you can call the function again.
$source – insert the URL source of the file or path to the script relative to your WordPress root directory. Src needs to be inside single quotes, like in the examples above. ($src=’ ‘)
$dependencies – insert the handle of a previously registered script on which the running of your new script depends. This is usually a library.
$version – pretty self-explanatory, right? The default value is false.
$in_footer – default value is false – which means you’re putting the script in the head of your HTML. True would put it before the </body>.
We won’t be adding $version and $in_footer as their default setting, false, suits our needs. In our case, we will create a paper-example.js file that depends on the Paper.js library.
Remember, there are many popular libraries, like jQuery, that are already included with WordPress. You don’t have to enqueue them, only add them as dependencies.
STEP 5: Enqueue your paper-example.js script and add paper-full.min.js as a dependency
First, let’s create a new file in your File Manager. Call it paper-example.js and save it in the same place you saved paper-full.min.js. Add console.log(“connected”) if you want to make sure that the file is enqueued properly.
To add a dependency to your enqueued script, we will simply add the handle ‘paperlibrary’ to the array. If we had more scripts to add as dependencies, we could do it in a single line, just by adding them to the array.
This should now be all connected properly, but we still have two major things to do.
STEP 6: Create a Canvas
We need to create a canvas on which the paper.js scripts will be displayed. This is how it should look by default:
Canvas is a HTML5 element and it can’t be added with WP text editor. The easiest way to do it is if you’re using a page builder or a plugin that supports writing custom code. You will be able to place the canvas element on your page, inside a row or a div (I tested it with Divi and SiteOrigin page builders).
You can style the canvas in CSS like you would style any other HTML element. I added the following code to my child theme’s style.css file to make it stand out a bit:
Note: You can have more than one canvas on your page. Just don’t forget to give them different IDs.
STEP 7: Using Paper.js Directly With Javascript
If you copy any paperscript demo code into the paper-example.js you will probably get frustrated by the “undefined” errors. I’m here to tell you, they are, unfortunately, expected.
The problem is WordPress doesn’t support paperscript, which means we will have to work around that. We need to use paper.js directly with javascript, as shown in the Paper.js documentation: http://paperjs.org/tutorials/getting-started/using-javascript-directly/.
To do so you need to create a global scope and define your variables in it.
Creating a Global Scope
We can make paper scope global by injecting it into window like shown in the code below. This accesses all Paper.js classes and objects through the paper object. We also have to define a paper scope using the paper.setup(canvas) function which will automatically create classes for us.
Note that handlers such as onFrame and onResize need to be manually installed on the appropriate object while working in JavaScript. With a properly set up paper scope, all we have to do is install these handlers on the existing view object (example = view.onFrame).
For the sake of this tutorial, I’ve created a simple script with 2 paths and one tool, so that you guys can see how to put a global paper scope and define variables inside it. A yellow rectangle that is spinning its head right-round all day is my path1 variable and an orange line drawing tool draws the second path. You can copy my code into your paper-example.js file (or whatever you called your file) and start working from there.
Make sure you’re defining your Paths, Tools, Projects, and Views separately inside your paper scope. When working in paperscript you don’t have to do this, but it is required when working directly in javascript.
Have fun with Paper.js!