Using External Libraries

by Allison Parrish

There’s only so much functionality you can pack into a single programming framework, and while p5.js comes with a lot of goodies, it doesn’t come with everything. In this tutorial, I’ll show you how to locate, download and integrate third-party p5.js-compatible libraries.

Third-party libraries

A third-party (or “contributed”) library is a chunk of Javascript code, usually contained in a single .js file, designed to work with p5.js but that doesn’t come with p5.js by default. In this tutorial, we’re only going to talk about Javascript libraries that are specifically designed to work with p5.js. The p5.js folks maintain a list here, and there are also instructions on the p5.js wiki about contributing your own libraries.

The library we’re going to use in this tutorial is RiTaJS, a library by Daniel Howe and contributors for working with text.

Installing a library

To use a library, you have to “install” it in your sketch. The basic steps of installation are as follows:

  • Locate the correct Javascript download of the library you want to install.
  • Download the library and make a copy in the libraries folder of your sketch.
  • Add a <script> tag to your sketch’s index.html to include the library when your sketch loads.

Locating the Javascript download is usually a matter of going to the home page of the library and finding the “download” link. Sometimes you’ll be offered the choice between a “minified” version and a normal version. The “minified” version works exactly the same as the normal version, but it has undergone an “optimization” process to make the code smaller. (Read more about the process here.). It’s always safe to use the minified version, but because the minification process makes it difficult for humans to read the code, you might prefer to download the full-size version if you want to be able to examine the code to see what it’s doing.

The RiTaJS download page is here. Download the file labelled rita-full.min.js and remember where on your computer you downloaded the file. (You may need to right-click/ctrl+click and select “Save Link As…” to download the file instead of viewing it.)

Installing a library

Once you have the .js file, go to View > Show Sketch Folder in the p5 editor. Your goal is to find the .js file that you downloaded, and copy it into your sketch’s libraries folder.

Copying a file. Why did I even make this

Modifying your HTML

Copying the file is just the first step. Next, you need to modify the index.html file of your sketch so that the library you just copied gets loaded by the browser before your sketch starts. The easiest way to edit your sketch’s index.html file is to activate the p5.js editor’s “sidebar,” which will then show a list of all files associated with your sketch on the side of your screen. Activate the sidebar by clicking on the Preferences gear icon in the upper right-hand corner of the screen, then selecting “Show Sidebar”:

Computer, activate sidebar

Select index.html in the sidebar. This is the web page associated with your sketch. The code for this page is automatically generated by the p5.js editor when you create a new project. Normally, this code simply loads the p5.js default libraries and displays the sketch, but you can modify the code to do whatever you want. Here’s what the HTML contains by default:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Untitled</title>
    <script src="libraries/p5.js" type="text/javascript"></script>

    <script src="libraries/p5.dom.js" type="text/javascript"></script>
    <script src="libraries/p5.sound.js" type="text/javascript"></script>

    <script src="sketch.js" type="text/javascript"></script>

    <style> body {padding: 0; margin: 0;} canvas {vertical-align: top;} </style>
</head>
<body>
</body>
</html>

To install a library, you need to add the following line to the HTML file, right above the line that begins with <script src="sketch.js"...:

<script src="libraries/YOUR_CONTRIBUTED_LIB.js" type="text/javascript"></script>

… replacing YOUR_CONTRIBUTED_LIB.js with the filename of the library that you want to add (the one you just copied to the libraries folder). For example, after adding the <script> tag for RiTaJS, your index.html should look something like this:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Untitled</title>
    <script src="libraries/p5.js" type="text/javascript"></script>

    <script src="libraries/p5.dom.js" type="text/javascript"></script>
    <script src="libraries/p5.sound.js" type="text/javascript"></script>
    <script src="libraries/rita-full.min.js" type="text/javascript"></script>
    <script src="sketch.js" type="text/javascript"></script>

    <style> body {padding: 0; margin: 0;} canvas {vertical-align: top;} </style>
</head>
<body>
</body>
</html>

When you upload your sketch to the Internet, make sure you upload your contributed library along with all of your other files!

Does it work?

Try out the following code to test if RiTaJS has been installed correctly:

► run sketch ◼ stop sketch
var field;
var button;
function setup() {
  createCanvas(400, 300);
  field = createInput();
  button = createButton("Get rhymes!");
  button.mousePressed(findRhymes);
  background(50);
  textSize(32);
  noStroke();
  fill(255);
}
function draw() {
}
function findRhymes() {
  background(50);
  var lexicon = new RiLexicon();
  var rhymes = lexicon.rhymes(field.value());
  if (rhymes.length > 0) {
    text(rhymes.join(" "),
      10, 10, width-10, height-10);
  }
}

Type a word into the box and click “Get rhymes!” If RiTaJS recognizes your word, and knows of other words that rhyme with it, they will be displayed to the screen. Don’t worry if you don’t understand the code—I’ll explain it in more detail in this RiTaJS tutorial!

If it didn’t work, check the following:

  • Is the correct .js file in your sketch’s libraries folder? (Make sure that you copied it into libraries and not some other folder.)
  • Did you add the <script> tag? Check the syntax of the line to make sure it matches the example above exactly. (Is there a closing </script> tag? Did you match all of your quotes and angle brackets?)
  • Is the content of the .js file you downloaded correct? Open it up in a text editor and ensure that the file looks identical to the one on the library website. (You might have accidentally downloaded, e.g., the GitHub page for the library, instead of downloading the Javascript code for the library.)