Feb 172013

I want to tell you a story. It’s a story of failure, heartache, and not a lot of sleep. It’s also set during a college course, so it’s not like lives were totally ruined by the end of this or anything.

The History

During the fall semester of my sophomore year, 1 of my classes involved building a software project from scratch. By “from scratch”, I mean “think up an idea, do the project plan, requirements, design, build it, etc.” – it was a “go through the whole waterfall development cycle exercise” thing. Anyways, a couple of my friends grouped up, and we started with the brainstorming. We decided we didn’t want to do some type of game but rather make something useful. This led to the idea of “Hey, let’s make a MapQuest of the campus” (it was 2003 – Google Maps wasn’t as big of a thing back then). And that was about the point where everything started going to crap.

After we pitched our idea and sat down to actually work on it, we realized we missed a few details that were going to be important in the pretty immediate future. First of all, we had to implement this project in C++, which we had just learned a couple of weeks before. By “learned”, I’m talking about the basics only, nothing more. We could do some logic and print to a console, but there’s no way we were able to let people interact with a GUI, which of course we had promised up front (whoops!). We also waited until after we committed ourselves to writing  this software that calculating directions is pretty hard to do well. This led to picking up a book on MFC (this would end up being a very bad idea later), and us really dumbing down the idea of “we’ll give you directions around campus” to something more like “we’ll do the horizontal path and then the vertical path”.

So…thinking that we had backtracked enough to get a project that was good enough for course work, we started on our coding. I built our UI, and the other group members started coding our “directions”. The night before this project was due, we thought we were in good shape, all we had to do was get the GUI and the main logic talking to each other and learn to draw on our map, and then we were set. That’s when the whole MFC thing came back to haunt us (remember when I said it was a bad idea?). It turns out, text in MFC is represented using CString objects, whereas vanilla C++ uses Strings. Whatever, different strokes for different frameworks, right? Wrong! They’re totally incompatible. It took all night and every bit of Google-Fu we could muster, but we got CString and String to play with each other without crashing our program, but we never did figure out how to draw that ****ing line on that ****map.

The Project

Over the years, the fact that we never could get our map project working bothered the crap out of me. Fast forward many years later. and I’m sitting around my apartment at the time trying to think of some project I could work on to expand my skill set a little bit, and through my Internet wanderings, I found links to the Google Maps Javascript API, and I decided that it was time to avenge my previous defeat at the hands of Programming Languages and Paradigms. Thanks to the Google Maps, not only do I no longer have to worry about drawing a ***damn line on a map, but Google even does directions! And they’re good ones too!

So I started working on a little project called Campus Navigator during free time when I felt the urge to spend my evenings doing something that I could pretend to be useful. By the way, that kind of time is a lot harder to come by than I thought it would be. But ultimately, I was able to build a Google Maps app that would give you directions around a campus.

Campus Navigator is written in plain old Javascript and XML. Part of the point of the project was for me to get familiar with Javascript, so it didn’t make a lot of sense for me to use something like jQuery or CoffeeScript. Having put together an auto-suggest box based on a guide I found through Googling, as well as parsing XML configuration files, I think the next project I write that uses JavaScript will probably make use of a library like jQuery or any of the other handy little utility packages out there, at least for DOM manipulation and reading data from files.

As for making the configuration files XML, I’m using XML because I can define and enforce schemas, which makes it easier on me for coding, and hopefully helps prevent anyone deploying this from entering in data that causes huge problems with Campus Navigator.

Configuring Campus Navigator

Campus Navigator is designed to be deployed on a university website without having to do anything more than edit the XML configuration files. The first is simply configuration/configuration.xml. Set the <latititude> and <longitude> tag values to the latitude and longitude values for the center of the campus, and decide whether or not you want to show multiple routes if Google can find more than 1 way to navigate between points (in the <allowMultipleRoutes> tag).  The configuration.xml file already has all the elements you’d need to get up and running, you just need to put in the correct values.

Next up is configuration/locations.xml, which does exactly what it sounds like, the list of locations on a campus that people might want to figure out how to get around to. Unlike configuration.xml, this file doesn’t have everything in already, just the root <campus> element. You’ll have to add the individual <location> elements yourself. The structure for the <location> elements is:

    The mandatory name of the location you're adding to the app
The whole address is optional, but this is the number and street name City State Zip Code - nothing special here
Mandatory latitude Mandatory longitude Optional description of the location

As you can tell from the above, to add a location all you really need is a name and some coordinates (here is a site that will help do it for you if you want). If you have a street address, that’s great, and used for info windows in the application (along with descriptions), but Campus Navigator can still find its way around based on the coordinates. I’m requiring coordinates because not every building on a campus is right off a road, especially for smaller campuses (my college only had a few roads going through it). By basing the navigation on the coordinates, neither you nor Google Maps won’t have to worry about that sort of thing.

Deploying Campus Navigator

Once you’ve filled out the configuration files, all you need to do to deploy Campus Navigator is to copy the navigator/ directory to the server that’s going to host the app. If you want an example of what the app looks like you can view a sample version using my alma mater, Elon University at here. If you like what you see, you can download the source code for this project from GitHub.

Using Campus Navigator

Once you visit the Campus Navigator website, just start typing in the names campus locales in the text boxes to perform a search for any location that has that text in the name. If you want more than a simple A to B, just click the “Add Destination” button to add other locations to visit up to Google’s limit. You can switch your starting and ending points, but at this point, there’s no switching of any middling locations. If sitting down at a computer to get directions around college seems a bit not-to-useful, Campus Navigator can even list directions on your phone, albeit not the cool turn-by-turn, update-as-you-walk kind.

Parting Thoughts

I don’t have any real plans to do much with Campus Navigator at the moment, although that could change if a lot of interest magically appears for it. While obviously designed for college campuses, there’s nothing limiting it to campuses. You could just as easily adapt the code for any area where you want to offer walking directions.

If you’re looking for a way to help people find their way around a college campus, and don’t mind some XML data entry, then Campus Navigator is for you. Once you put it on your site, the only thing that needs actual maintenance is the list of locations on campus, which is controlled entirely by 1 file, configuration/locations.xml. One of the advantages to using XML in the configuration, aside from enforcing a schema, is that it’s pretty easy to follow along with, so anybody on your campus can keep the locations list up-to-date and the application accurate.

I hope people can find Campus Navigator. If not, well, I learned a little Javascript, and published my first open-source project, which is the important part for me.

 Posted by at 3:18 AM