November 3, 2010

DIY with Perforce's JavaScript API, Pt. 1

Traceability
Flexible Workflows
Integration
What's New

This two-part article is about how I learned P4JsApi and some of its surrounding technologies.  My hope is that it’ll help you get up to speed more quickly.  So…

Part One: Getting Up To Speed

The recently released JavaScript API for Visual Tools is a pretty cool piece of technology—it allows you to plug your own applets right in to both the P4V and P4Admin clients, all the while talking to the Perforce server.  This sounded perfect for me, someone who does a lot of prototyping: a brand-spanking-new cross-platform environment that lets you Do It Yourself—sweet!  The only problem was that my JavaScript skills were rusty; I needed a small, un-intimidating project to get me started…

A New Process Monitor

One of the Perforce department heads recently asked me about possibility of making a process monitor—something that keeps an eye on processes currently running on the server.  It’s true that P4Admin currently has a process monitor, but it’s mostly text and could do with a shiny new makeover.  This sounded great for my purposes; I wanted something that would do some fancy drawing, talk to the Perforce server, and have some interaction with the user.  Plus, I secretly wanted to make an applet that looked like something you’d see on the bridge of the Starship Enterprise, and I knew there were are a bunch of JavaScript libraries that could help me do that.  A new process monitor would be just the thing…

So I set about making it, and I’m here to tell you what I learned in the process.  Here’s a screenshot of what I ended up with (you can’t see from the picture, but the bars are animated, just like the future!):

Process Monitor screenshot 1

Looks pretty good to me.  About those colors: When a process has been running for period of time determined by the user, its bar turns from blue to orange.  When the user clicks on one of the process bars, a little translucent box glides in to view, just like on the Enterprise's computer:

Process Details screen

Then there’s a preferences dialog that lets the user change some options…

Based on these screenshots, I think I’ve met my initial goals: fancy drawing (well, a little fancy), talking to the Perforce server, gathering input from the user, and yes, it almost looks like it could be on the Enterprise.  The rest of this article details how I got there…

Diving Into The JavaScript Pool

My first order of business was to refresh my JavaScript skills.  I did some reading, worked through some tutorials, and watched some videos; all of the following were helpful:

  • The W3Schools JavaScript tutorial is a very good place to start: http://www.w3schools.com/js/default.asp.  It teaches most of the basics; not enough to write good JavaScript mind you, but it answers a lot of questions.
  • The book JavaScript: The Good Parts by Douglas Crockford.  I read this book early in the learning process, and I need to go back and re-read it now that I know enough to cause trouble.
  • Google’s HTML/CSS/JavaScript videos: http://code.google.com/edu/submissions/html-css-javascript/.  This series of videos is great; they shows you how to use HTML, CSS, and JavaScript, and teach a set of best practices, including how to write code that is easier to maintain by keeping markup, visual style, and logic separate.
  • The JQuery tutorials at http://docs.jquery.com/Tutorials.  JQuery is just one of many JavaScript libraries that can help your applets look like the future—for instance, JQuery supplies the elements that slide in and out of view.  In hindsight, I should have spent more time learning JQuery and the JQuery UI before starting to code (more on this later).
  • The Mozilla Canvas Tutorial at https://developer.mozilla.org/en/Canvas_tutorial.  Canvas is an HTML element that lets you draw your own custom stuff.  After I realized that the free Google charts weren’t going to be flexible enough to do what I wanted (more on this later too), I decided to do custom drawing for the bar chart in my app using a Canvas element.

Getting Set Up In A P4 Client

Ok, so after I had a little JavaScript under my belt, the next step was to put something in P4Admin that I could actually code to.  How to get this up and running?  This was one of those cases where there’s no substitute for reading the docs, so here’s a link: http://perforce.com/perforce/r10.1/manuals/p4jsapi/p4jsapi.pdf

You should be able to get started by going through the first few sections, specifically Enabling Applets, The Permissions Table Entry, The Central Settings File, and Programming Applets.  You might as well read the whole thing though; you’ll probably need it all at some point.

Oh, and make sure you’re running a Perforce client from release 10.1 or later; P4JsApi wasn’t in prior releases.

A Word On Security

With freedom comes responsibility, yes?  So I got to use all this cool P4JsApi stuff, but given that one uses it to access the company’s crown jewels (via the Perforce server), I also needed to watch for obvious security holes.  It turns out that the main issues to look for have to do with gathering and disseminating data: anything you collect from the server, and anything you collect from the user, needs to be scrutinized and groomed before creating and modifying HTML with it.

This isn’t hard to do, but you must remain vigilant; the main thing is to read the Security section in the manual I linked to above.  Read it all, and follow the suggestions.  And when you’re coding, pay particular attention when you’re writing to HTML.  Make sure that you’re not passing executable JavaScript to the browser!  To prevent this, P4JsApi gives you the encodeForX methods, which you can use to wrap around any data that could potentially be malevolent. For an example, check out the following code snippet, where I take some data from the server and show it to the user:

document.getElementById("statusLabel").innerHTML = P4JsApi.encodeForHTML(process.status);

In this case I have an object I’ve created, called process, which contains a string in its status field that comes directly from the server.  Wrapping process.status in the encodeForHTML method ensures that there is nothing in the status field that is going to execute when it gets written out to HTML.

Likewise, if you know that your output is going to be an integer, you can use the parseInt method for even better security, like so:

document.getElementById("idLabel").innerHTML = parseInt(process.id);

In this case, I know that process.id is supposed to be a number, so I wrap it in parseInt to ensure that it can only be a number or JavaScript’s NaN.

So, what are the chances that there is an executable script in a process’s status or id field?  Admittedly slim.  But a motivated and malevolent user can find ways to insert executable script into your data; using these methods is your first line of defense to prevent that from happening.

Ok, so now you’ve got an idea about how to use JavaScript, you’ve got a skeleton applet implanted in either P4Admin or P4V, and you know a few ways to slow down the bad guys.  You’re ready to start doing some coding!

Next up in Part Two of this article: Nuts and Bolts, or how to actually use P4JsApi…