The Pin Map, currently in its third iteration, is designed to allow instructors in online courses deploy an assignment centered around placing a pin or pins on a map. This might be as simple as having students share what city and state they are from, or it might be as complex as having students drop multiple pins marking public art galleries or festivals across their hometown. The Pin Map was designed to be flexible, highly custom from course-to-course, and directly editable by instructors and instructional designers.

Brief History

Version One

The first iteration of the Pin Map was used only in one course: an orientation course for all students at The University of Alabama. There were no options and no ability to customize anything. Students could only enter their city (optionally), state, and country. That information was then geocoded using the Google Maps API to retrieve a latitude and longitude, and the marker was placed. Version One did include the ability to pass a grade back into the LMS using the SCORM standard, though that feature was mostly unnecessary for an orientation course.

The markers were stored on a SQLite database on a campus web server, with the minimal backend logic being handled by custom PHP and a PHP library called Medoo. Many complications like Cross Origin Resource Sharing were identified and solved.

Version Two

Version Two of the Pin Map was much more ambitious than version one. In this version, I could customize the fields included in the map for any individual course, and there were multiple field types outside of text like links and images. The tileset, too, could be changed to dramatically alter the look and feel of the map, and map settings (like minimum zoom, maximum zoom, starting latitude and longitude, etc) could be customized as well.

Version Two was also backwards compatible with version one, meaning that old maps would continue to work just fine. Blackboard template variables were used to allow maps to properly carry foward after a course was copied in Blackboard. The backend logic was expanded to accommodate all of these changes, including the ability to test everything on a development server before going to production.

Current Version

All of the expansion in version two came with a trade off, though. I had to manually piece together JSON files and ZIP them into a SCORM-compliant package for every course that had the map added. While not a significant amount of work, it was easy to make errors creating those packages. Further, the code was increasingly becoming spaghetti code. It was hard to maintain and impossible to add new features. When I began working with faculty member who wanted significant new features, I began the process of rewriting the whole application.

For Version Three, I started from scratch and adopted Laravel as the backend and Vue for the frontend. More about these in the technology section. These have been critical in helping maintain the code base. A change that would previously have taken hours now takes minutes. Version three only adds minimal functionality improvements (like the ability to have more than one marker per student on the map and more than one map in the course), but it puts the improvements of version two directly into the hands of the instructor and instructional designer. And it allows for further expansion of features down the road. Because it is a total rewrite, it is also significantly more visually pleasing than it had been previously. It also uses modern ES6+ Javascript features which has benefits I will discuss in the technology section.


Laravel (Backend)

Laravel is the most used PHP backend right now, and has huge community support with lots of great tutorials and documentation. The biggest challenges that I had using Laravel had nothing to do with Laravel itself. It was learning a real MVC framework with controllers, models, migrations, views, middleware, and routing all at once (and deploying to a Linux server where I don’t have shell access).

But it was so worth it. Laravel makes things like user roles, authentication, authorization, and API requests easy.

Vue (frontend)

I chose the Javascript framework Vue for the frontend, partially because of Laravel’s out-of-the-box support, but primarily because I found it significantly easier to learn than React or Angular. Having a reactive frontend was essential to the design pages, where I wanted faculty and instructors to be able to see their changes in real time.

In addition to Vue, I used one of the major Vue plugins Vuex. Vuex handles state management in Vue in a central location. This makes sense when you understand how Vue uses components for visuals and logic. For as simplistic as a map application sounds, you’d be surprised at the number of models are required and need to be tracked. Consider that you need to store or key off of information for the following:

  • Map
  • Marker
  • Field (remember, they’re dynamic)
  • Field Types
  • Section (the courses themselves so we can track which map is attached to which course)
  • Tilesets
  • Assignments (each course can have multiple separate maps, so a further delineation is required)
  • Users (those creating the maps)
  • Students (those filling out the maps)

This does not include include the pivots, which can get pretty complicated when considering how this all attaches to one another.

I’ve also used Vuetify, which an adapted-for-Vue version of Google’s Material Design spec. It’s been fine, and it served it purpose in terms of making layout and theme easy to get started on.

Development Environment

Getting started developing with Laravel and Vue is as easy as any other type of project. That is to say, not nearly as easy as it should be. Homestead (on Windows) and Valet (on Mac) make it relatively simple, but I ran into some significant issues early on. Suffice it to say that I now know all of the particulars needed to get composer to run using PHP 7.0 instead of 7.2 (because the Linux server only supports 7.0) in both a Vagrant VM and on a Mac using Brew.

I still find Webpack to be a nightmare. Laravel Mix is a great resource, but as soon as you need to customize it (say, to use Babel on a specific NPM dependency), you basically still have to learn Webpack. Webpack is not required to use with either Laravel or Vue, but it is still the defacto standard and what most resources point to. In the future, I may look more closely at Parcel or using the Vue-CLI (though it uses Webpack behind the scenes).

Other Thoughts

I expect to expand on this page in the future, both because I have more to say and also expect further development. What I can say is that using Laravel and Vue have made me enjoy web development in a way that I never truly enjoyed it before – I often find myself spending hours on Pin Map at home when I don’t have to be working.