Lucid Mesh: Barely Adequate Guide

Showing posts with label Barely Adequate Guide. Show all posts

A Barely Adequate Guide to the Google Blogger API using Ruby

For some time now, I've been wanting to do some things with this blog that are just too tedious to do by hand. For instance, I'd like to download all posts with pictures to have a local copy, you know, just in case. Google leaves a bit to be desired in this regard with its backup feature. I would also like to get a word count of all of the posts I've written, just because I'm curious. These things would be done best with an API, so that's what this post is going to explore.

A Barely Adequate Guide to Displaying Chess Games with JavaScript

I've done a few of these Barely Adequate Guides in the past, the idea being that I want to explore how to do something with code that I've never done before, and I'll figure it out while writing the post so that we can all see my thought process as I go about solving the problem of getting something new up and running. This time I want to bring together two things I love doing in my free time: programming and chess. I wouldn't say I'm an especially good chess player—I'm quite mediocre actually—but I love the game, and I love learning it and reading books about it.

A Barely Adequate Guide to JavaScript Canvas

Whenever I want to add a new feature to this blog, I write a post describing the process of researching and implementing that feature first. I've done two Barely Adequate Guides so far, one on syntax highlighting with JavaScript and one on JavaScript charts. The goal with these guides is twofold. First, I get to document what I'm learning about how to implement these features for future reference. Second, it shows at least one way of researching, choosing, and working with a new software library starting from square one.

Nearly everything we do as programmers has already been done before. Maybe not exactly in the same way as we're trying to do it this time, but pretty much every component that makes up any given project already exists in some form out on the Internet already, probably in more than one library. That means we have a choice as to how to spend our time. We can either write that component from scratch and know exactly how it works, or we can find a library and integrate it into our project. Each method has its benefits and costs, and I normally will spend at least a small amount of time looking for a ready-made solution. If I can find one quickly, it's robust, and it has a decent API, I can save a lot of time by programming at a higher level than I would otherwise.

An Initial Search

For this Barely Adequate Guide, I want to learn about the HTML5 canvas and start using a JavaScript library that makes using the canvas even easier. I'm planning some articles that will make good use of animated drawings, and it should prove useful for future posts as well. I start, as I always do, with a Google search:

I start with the basic "javascript canvas" search terms to see what comes up. (By the way, I just had a great experience getting this screen cap. I switched from Windows to Linux about half a year ago, and this is the first time I did a SHIFT-PrintScreen. The cursor turned into a cross-hairs and I selected an area to capture. Then a dialog box appeared where I could name the file and choose where to save it. This is a way better experience than having to muck around with Paint on Windows. Linux: 1, Windows: 0.) Here are the top ten results:

This looks like a lot of HTML5 canvas stuff. I dive into the first link, but it looks like a lengthy tutorial so I back out. It's from the Mozilla folks and it's probably good, but I don't want to spend that much time right now. The next link leads me to a brief description of the HTML5 canvas with some code samples. After scanning through the samples, it's clear that most of the interaction with the canvas is already done through JavaScript, but I want something with higher-order functionality that will make drawing and animation even easier.

I skip past the other HTML5 links and take a look at the Fabric.js library. This looks promising. The Fabric.js library appears to have a lot of features, good documentation, and active support on Github. I take note and look at the next link. It's actually a chapter out of a free online book called Eloquent JavaScript. It looks quite good, but not what I need right now so I bookmark it and keep searching. With the tenth link, I've reached the end of the first page of search results, learned a bit about the canvas, and found one higher-level library.

Refining the Search

I could continue paging through the results, but I think I'll have better luck refining my search.

Google Search: best javascript canvas library

That's right. I want the best. I figure by using the 'best' search term, I'll get at least a few links that will rank or review different JavaScript libraries. I wasn't disappointed:

It looks like six of the top ten results are rankings or reviews of JavaScript canvas libraries. Then there are three sites for popular canvas libraries (EaselJS, Fabric.js, and Pixi.js) and another site for a JavaScript chart library that happens to use the canvas but is not a general purpose drawing library. The second and third links catch my eye because they're from Stack Overflow, a reliable programmer's resource even if they tend to close these types of questions.

The second link leads me to a comparison table of JavaScript canvas libraries in a Google doc. It looks a little out of date and doesn't have too many different comparison points, but it's still useful to browse through. I find Pixi.js, EaselJS, and Fabric.js at the top of the list again, along with Paper.js. Both Paper.js and Fabric.js appear to be much larger than the other two libraries, although Fabric.js is more modular so it's potentially comparable to the smaller libraries if I only use the core of it.

I follow the links to each library's website, and I find that they all have demos, example code, and documentation ranging from good to great in quality. With the short time that I spend on each site, I feel that Paper.js and EaselJS have a bit more complicated API, while the Pixi.js and Fabric.js APIs look immediately familiar. Then I visit each of the GitHub repositories to get a sense of how active and popular the libraries were. They all seem to be well maintained with regular and recent checkins and good notes in the readme files for getting started. Pixi.js has by far the most watchers, stars, forks, and contributors, with the other three libraries having similar stats to each other for the most part.

Between its potential ease of use, small size, and popularity, I decide to go with Pixi.js. I wouldn't normally go with the crowd so quickly when choosing a library, but in this context it's a reasonable course of action. If this decision was for a more complex project that depended on a drawing library for its success, I would do a more in-depth analysis and probably experiment with all of the top contenders, but for using a library with this blog, any of these libraries would likely be more than adequate. I want something I can learn quickly, and I want to waste as little time as possible deciding which library to use so I can start learning the library sooner. Clear code examples and popularity are a decent first-order proxy for a detailed evaluation in this case.

Experimenting with Pixi.js

The first thing I need to do to start playing with Pixi.js in my blog is to load the JavaScript library. I can either load the source file from https://cdn.rawgit.com/GoodBoyDigital/pixi.js/dev/bin/pixi.min.js or clone the git repo from https://github.com/pixijs/pixi.js, host the pixi.min.js myself, and load it from that location.

One easy way to host JavaScript files is to set up GitHub Pages with this tutorial, make a javascript folder to dump in any JavaScript files you want, and push them up to GitHub. Then you can source the files from your own <username>.github.io URL. I chose to load the source from the main GitHub project, so I added this line within the <header> tag of my Blogger template:

<script src='https://cdn.rawgit.com/GoodBoyDigital/pixi.js/dev/bin/pixi.min.js' type='text/javascript'/>

With the library loaded, I can start experimenting with drawing shapes on a canvas. Let's start with drawing a simple line. On the examples page on GitHub there's a Graphics example with sample code. Pulling out the necessary setup code and the code to draw a single line gives me the following first attempt:

<div id="canvas-line" style="width: 550px; height: 400px">
</div>
<script type='text/javascript'>
 var canvas = $('#canvas-line');
 var renderer = PIXI.autoDetectRenderer(canvas.width(), 
                                        canvas.height(), 
                                        { antialias: true });
 canvas.append(renderer.view);

 var stage = new PIXI.Container();

 var graphics = new PIXI.Graphics();

 graphics.lineStyle(10, 0xffd900, 1);
 graphics.moveTo(50,50);
 graphics.lineTo(500, 300);

 stage.addChild(graphics);

 animate();

 function animate() {
  renderer.render(stage);
 }
</script>

The code starts out by defining a <div> with an id that I can refer to in the JavaScript code. Then the JavaScript finds the element with that id, creates a renderer and a canvas, creates a stage for adding graphics contexts, and creates the first graphics context. The graphics context is what's used to draw things, in this case a line. The line style is defined for the context and then the line is defined with a starting point and an end point. Finally, the context is added to the stage and the animate() function is called to render the drawing. The result looks like this:

Not too bad, but a bit rudimentary. Let's try something a bit more interesting. How about an oscillating sine wave. For this drawing, I'll have to add animation, but that shouldn't be too hard because animation support is already there by default in the animate function. The hardest part is constructing the sine wave from line segments. Here's the code:

 var canvas = $('#canvas-sinewave');
 var renderer = PIXI.autoDetectRenderer(canvas.width(),
                                        canvas.height(),
                                        { antialias: true });
 canvas.append(renderer.view);

 var stage = new PIXI.Container();

 var sinewave = new PIXI.Graphics();
 stage.addChild(sinewave);
 sinewave.position.x = 75;
 sinewave.position.y = 200;

 var count = 0;

 animate();

 function animate() {
  count += 0.1;

  sinewave.clear();
  sinewave.lineStyle(4, 0xff0000, 1);

  var amplitude = Math.sin(count) * 100;
  sinewave.moveTo(0, 0);
  for (var i = 0.1; i < 6.3; i+=0.1) {
    var x = i*63.5;
    var y = amplitude*Math.sin(i);
    sinewave.lineTo(x, y);
    sinewave.moveTo(x, y);
  }
  renderer.render(stage);
  requestAnimationFrame( animate );
 }

In this case I create a graphics context for the sine wave outside of the animate function and set its origin to where I want the sine wave to start. Then in the animate function, I increment a counter that determines what the amplitude of the sine wave is for the current frame and draw out the sine wave with line segments. Finally, I have to request an animation frame to advance the animation. The result looks like this:

Mesmerizing. That's not bad for a few hours of experimentation and a couple dozen lines of code. Now I can add animated graphics to my posts, and I learned a new trick to add to my repertoire. Pixi.js is a pretty deep library, and you can do a ton of different things with it. It would probably take months to become proficient with it, but getting a handle on it in a few hours was worth the time. If you're in need of graphics or animation for your website, it's a good place to start.

A Barely Adequate Guide to JavaScript Charts

I show a fair number of charts on this blog, especially when I'm talking about my Nissan Leaf data, and I've been getting tired of showing boring pictures of charts generated from Google Sheets. Sure, they look nice and it's easy to do, but I wanted something a little more interactive. I thought I could put in a little more effort and spruce up my data presentation a bit, so in the vein of my last Barely Adequate Guide, I'm going to write this post while figuring out how to use a JavaScript charting framework. The idea is to come up to speed as fast as I can on at least one charting framework, and get a functional example working in this post. No detailed analysis. No in-depth guide to every feature. Just do the simplest thing that could possibly work. This shouldn't be too hard, so let's get started.

Figuring Out a Chart Framework

First as always, it's time for a Google search. After looking up "javascript charts," on the first results page I get an even distribution of chart frameworks and sites that list chart framework options:

Taking the first one from the list, Highcharts looks beautiful, and right on the demo pages is a link to JSFiddle where I can play with the chart options and fiddle (heh) with the code so it's exactly how I want it before including it in the article. Here's my first attempt with the demo chart from Highcharts for a chart I use a lot, the scatter plot:

This is pretty slick. You can highlight data points with the cursor, zoom in by dragging a box around points, and zoom out by clicking the 'Reset zoom' button. To get the chart to draw correctly, I had to do a few things. First, I included the required jQuery JavaScript library in my Blogger HTML template at the bottom of the header with the following line of HTML:

<script src="//ajax.googleapis.com/ajax/libs/
  jquery/1.11.2/jquery.min.js"></script>

Then I added a couple more lines to the HTML of this post so that the Highcharts JavaScript will load and a <div> is defined for holding the chart where it should be drawn:

<script src="http://code.highcharts.com/highcharts.js">
</script>
<script src="http://code.highcharts.com/modules/exporting.js">
</script>
<div id="test_chart" style="height: 400px; margin: 0 auto; 
  max-width: 800px; min-width: 310px;"></div>

The two <script> tags only need to be included once per post that uses charts, and I don't include it in the Blogger template so that it doesn't needlessly load the Highcharts JavaScript for posts that don't use it. That means there will be a little redundancy when multiple posts that use charts are loaded on the same page, but I'm okay with that inefficiency.

The last step was to copy the chart code, including the data, into my post. I'll show a snippet of it here:

<script type="text/javascript">
$(function () {
  $('#test_chart').highcharts({
    chart: {
      borderRadius: 8,
      type: 'scatter',
      zoomType: 'xy'
    },
    // boatload of chart options and data
    // ...
  });
});
</script>

The complete code can be found at JSFiddle, where it's trivially easy to play around with different settings and see how the chart changes. The fact that they have all of this demo code posted at JSFiddle is great. I couldn't believe how easy it was to get this working. The experience was totally seamless. They also have excellent documentation on all of the chart options in an easy to browse format.

Applying What I've Learned

Now that I have a working chart, the next task is to see how easy it is to convert some of my own data into the right format and include it in a chart. After all, I need to have charts with my own data in them, right? Since I have a bunch of Leaf battery data, I'll use that. I found that I first had to format the data so I could easily add it to the chart's JavaScript. In Google Sheets I separated each data set into its own sheet with a column for temperature and another column for estimated range. I ended up with four sheets for the data sets for 2012H2, 2013H1, 2013H2, and 2014H1.

I saved each sheet to my computer as CSV files, and then using a little Vim-fu, I added the necessary brackets to get the data into the [[temp1, miles1], [temp2, miles2], …, [tempN, milesN]] format needed for the chart's data series section. Then it was a simple copy and paste into JSFiddle to check that the chart worked, and another copy and paste of all of the JavaScript into the post. If I was going to do this a lot, I'd probably write a script to generate more of the JavaScript, but for this test the manual editing was fine. I end up with this:

Nice! The other neat thing about these charts is that you can click on the labels in the legend to toggle the data sets on and off—very useful when you have a lot of points, like in this chart. I'd say this chart is sufficient for the things I want to do, so this exercise has been a success. But what about other options? I haven't even looked at anything else.

Looking at Other Options

To quickly evaluate some other options, I took a look at the rest of the top 10 Google results. The 15 Best JavaScript Charting Libraries article has a decent overview of the main charting libraries, including Highcharts, but it doesn't go into too much detail about what differentiates the libraries. The Wikipedia comparison has a more complete list of charting libraries, and at least on the metrics chosen by the Wikipedia authors, there really isn't much differentiation among them. All of the libraries more or less provide similar features, so unless there's a critical features that only some of the libraries support, it probably boils down to a matter of taste. Here is what I found from my own brief look at a few of the other libraries.

Chart.js - This looks like a simple, straight-forward library that allows you to create clean, elegant charts without a lot of extra cruft. It looks like it's a bit too simple for the features that I wanted, but if I wanted a no-frills chart that looked great, I'd definitely consider Chart.js.

Google Charts - It looks like Google exposed the API for their chart creation feature in Google Sheets with this library. The documentation looks great, the charts are easily recognizable by anyone that uses Sheets, and they seem to be very fast. They also look to be quite fully featured with scatter plots and zoom capability.

D3.js - This library is like the assembly language of charts. It gives you incredibly precise control over every aspect of charting, and it allows you to make all kinds of different charts beyond the basic bar/line/pie charts that most libraries offer. The flexibility of this library is readily apparent in this gallery of D3.js charts, and it's truly astounding. Unfortunately, I don't have the time to get good at something this complex.

amCharts - Probably the most beautiful charts out of the box, amCharts is an extensive charting library that's as easy to use as Highcharts or Google Charts. There's also an online chart builder that looks pretty nice—kind of like a JSFiddle made specifically for their library. The library requires a license for commercial use and otherwise has an embedded link on every chart.

There are many more options, but they all start to look alike after a while. I would have to use them extensively to ferret out more of the trade-offs, and I'm sure each one has situations where it would be the best choice. As it is, I'm quite happy with Highcharts. It was super easy to get up and running for this blog, and the documentation is so good that I can quickly find what I need, even if I'm only using the library a couple times a month. Who knows? Because of how easy it is to use, I might end up using it more than that. We shall see.

A Barely Adequate Guide to Syntax Highlighting Code in a Web Page

Since I talk about programming somewhat frequently, I figured it was about time that I add syntax highlighting to my code examples. This post will be an interesting experiment because I only have a vague idea of how to do it, but I think I can figure it out quickly enough while writing an article about it at the same time. I'll set out three goals for this post:

Figure out how to add syntax highlighting to my posts on Blogger as quickly as possible.
Do a little survey of different ways to do syntax highlighting. This won't be comprehensive, but hopefully will give a few reasonable alternatives.
Write fairly continuously. I've wanted to do a little writing exercise to work on writing faster, and here's a good opportunity to do it.

Okay, with that settled, are you ready? Let's see how this turns out.

A Brute Force Attempt

I'll focus on highlighting Ruby code in this post, and I normally do my Ruby coding in Vim. I know Vim has a way to convert syntax highlighted code to HTML with the command :TOhtml. I'll make a little code snippet that has a decent variety of Ruby elements and run the converter on it to see what it looks like. Here it is:

class Speaker
  # Greet someone
  def self.say_hello(params)
    @name = params[:name]
    puts "#{params[:greeting]}, #{@name}"
  end
end

Speaker.say_hello({greeting: "Hello", name: "Sam"})

That looks pretty good right off the bat. I could tweak the CSS a bit to change colors, but other than that, it's straightforward. The problem with this method is that it's not too easy to go back and convert all of my old code samples to add syntax highlighting. I have to copy each one into Vim, run the converter, and then copy the HTML back into Blogger. I'm not looking forward to that. Also, I had to remove some of the generated HTML because Vim produces HTML for an entire web page, and I just need the <style> and <pre> tags and related content. I don't want to have to nip and tuck the HTML for every code snippet on my blog.

There Must Be a Better Way

There must be a way to use a JavaScript library to do the highlighting for me. It's time to pull out the programmer's most essential tool - Google. If I do a search for "syntax highlighting javascript," I get the following top 10 list:

That looks mighty promising. We've got a number of JavaScript syntax highlighters, another list of them on Stackoverflow, and a comparison down at #9 that may prove useful for my second goal. Let's take the first one off the top of the list.

Highlight.js

Highlight.js looks really easy to use. All I have to do is add three lines to my template header in Blogger as described in the basic usage instructions, wrap my code in <pre><code>...</code></pre> tags, and format the code in HTML with the exact tab spacing that I want. Really, I can just copy the code out of Vim and into the HTML, and it should work. The script is even hosted so I don't have to figure out how to add it to my Blogger template, although I'm sure that's easy, too. Here's what the result of all that looks like:

class Speaker
  # Greet someone
  def self.say_hello(params)
    @name = params[:name]
    puts "#{params[:greeting]}, #{@name}"
  end
end

Speaker.say_hello({greeting: "Hello", name: "Sam"})

Nice! To change the theme, you can change the default.min.css to a number of different CSS templates. There's even a live demo at highlightjs.org so you can easily pick a theme that you like. I like to light up my code like a Christmas tree because it's easier for me to recognize different code elements. I also want a theme with a black background and good contrast so it doesn't seem like I'm looking through a dense fog at the code. Finally, I like my keywords to be blue or purple, just because. I thought the Tomorrow Night Bright theme was okay, so I went with that one. I might change it in the future, though, so no guarantees that what you see here is that theme.

Wait, We're Done Already?

Yup, that was actually easier than I thought it would be, and I'm happy with how easy it is to go back and convert my other code samples to be highlighted. But not today. Actually, we're not quite done, yet because I only showed two highlighting options. I'll spend a few minutes looking into the other options that turned up in Google.

Prism.js: Prism.js seems pretty nice. The website is straightforward, there's some good API documentation, and there's a test drive page where you can see what code for your favorite language will look like in one of their six prepackaged themes. There aren't as many themes or supported languages as Highlight.js, but it already supports Swift, which is pretty impressive and means it's definitely in active development. Prism.js does support line numbers, which is nice for long code listings or if you want to reference specific lines in your text. There's no hosted JavaScript as far as I could tell, so you'll have to download it for your own use. Most people will probably do this anyway. It's so much easier to do a quick-and-dirty setup with a hosted instance of the plug-in.

SHJS: SHJS doesn't look like it's been updated since the end of 2008. That's not necessarily a problem, but the other syntax highlighters have probably advanced beyond it. It does support a decent selection of languages, although not as many as Highlight.js, and a decent set of themes, including many of the default themes from popular editors such as Emacs, Eclipse, and Vim. You can test out how they look with a snippet of C++ code on the website. As with Prism.js, there is no hosted JavaScript available.

Rainbow.js: Rainbow.js looks to be a more basic option, with a bare-bones, although probably sufficient, single-page website. It supports 18 languages, which is on the low side of all of these options, but they're all the most popular ones so it should work for most people. The minified JS file is tiny at only 1.4kB (no hosted instance again), and it includes a decent set of predefined themes. You can't preview the themes on the website, though.

SyntaxHighlighter: The language support is also on the low side with 23 different language 'brushes' included. As far as I could tell, there was only one default theme available, so if it's not to your liking, you'll have to tweak the CSS yourself. It does support line numbering, and the styling of the line numbers looks especially nice. Once again, there was no hosted instance of the JavaScript.

Prettify: Prettify supports a nice variety of languages, and it's the only one of these highlighters, other than Highlighter.js, that auto-detects which language it's highlighting. It only has a few prepackaged themes, and they are shown as previews on the website. It does support line numbering, but only labels every fifth line by default. Getting it to number every line takes a bit a bit of extra CSS code.

Syntax highlighting code with JavaScript - Stack Overflow: The answers to this Stack Overflow question had most of the JavaScript syntax highlighters from the first page of Google search results and a few more. Since the search results already turned up enough, I won't go into the few additional ones listed here.

Completely unfair comparison of Javascript syntax highlighters: The guy that did Highlighter.js wrote up a nice comparison of Highlight.js, SHJS, SyntaxHighlighter, and Prettify. It's now three years old, so things could have changed from when it was written, but it's a nice read for understanding what to look for in a Javascript syntax highlighter. It is admittedly biased, but it convinced me that my original choice of using Highlight.js was adequate.

In the future I'll probably figure out how to include the Highlight.js code in my Blogger template instead of linking to the hosted instance of the code, and I'll tweak the colors and code block decorations a bit. Overall, I was quite pleased with how quickly I could get the syntax highlighting working. I should have tried it out sooner! It's nice to have some colorful code now.

Search This Blog