David Seah / Code
Process Journal: Computer Programming Explorations

“Project Second” is the codename for my web app. Since I’ve never written a Javascript web app before, I’m facing a significant learning curve. However, I’ve developed similar systems in other languages, database programming excepted, so it’s a matter of just pushing through and figuring out how to make the code fit together and work. I’m documenting it all in my “Code” process journal blog.

This is not a working application. This is an application I am developing. This page is an index for my development notes.

While the learning is going slowly, I’m excited about finally developing the ability to create web-friendly versions of my various paper productivity designs. It’s also nice to be programming something again, facing old challenges with a fresh set of constraints.

To present the content more logically, this page summarizes what was achieved in chronological order below. New programmers might find the process interesting. Each entry represents between 4-8 hours of research/work.

NOTE: the entries were written primarily for myself, and have not yet been cleaned up for maximum clarity. YMMV!

Stage One: Make a Home Page with Tasks

I have a home page that I used for all my computer browsers, hosted on my web server, with my favorite jumping-off links to sites I use frequently during the course of my work day. Since I look at this page dozens of times a day if not more, this is the ideal place to put my todo list!

The first stage of developing my own productivity web app, therefore, aspires to making a “favorite links” page with a to-do list integrated into it.

1. Seeking the All-Singing, All-Dancing HTML5 Framework

I decide to use WordPress as the underlying codebase, building my web app on top of it as a WordPress theme. This has the side bonus of sharpening my knowledge of WordPress internals.

2. Kickoff: Development Testbed

Development Chores!

• Setting up Subversion for source control.
• Installing a fresh copy of WordPress.
• Set up a child theme of “TwentyEleven”, an HTML5 theme.
• Committing sources
• Setting up DreamWeaver and Coda

With this done, I’m ready to start coding!

3. PSEC: Code Execution Start

Where does WordPress end and my application begin? I am forced to trace the WordPress startup to see where my code needs to be placed. There are several places that execution is passed to my code from WordPress, each with its own set of expectations.

4. PSEC: Code File Organization

Now that I know where my code exists in relation to WordPress, I come up with a way to keep PHP and Javascript files separate-but-manageable under my theme directory. I avoid hard-coding paths, because I want the codebase to be easy-to-install on any WordPress.

5. PHP Debugging in Chrome

Debugging PHP via the server error log is tedious. I installed the ChromePHP extension so I could monitor error messages in near real-time via the Javascript console, then wrapped it in my own class to provide some additional functionality.

6. PSEC: Database Table Creation

A workable development environment is in place. It’s time to write code.

I started by defining a database schema suitable for tracking tasks in a productivity app. Then, I figure out how to use built-in WordPress database functionality to actually create the tables.

7. SQL Crash Course

After dipping my toe into database programming yesterday, I realize I need to refresh my understanding of what a database is. I rapidly scan an old MySQL 3.0 reference manual and extract the good parts: the elements of a database, joins, built-in functions, and SQL syntax.

8. PSEC: Creating MySQL Tables in WordPress

With a firmer knowledge of SQL syntax, I’m able to create tables I need within WordPress, and put data in them. I also add some skeleton code to handle changes to the database version, so the table structure can be updated as needed.

9. PSEC: Designing HTML/CSS Widgets

With a rudimentary database available, now I need some way of displaying the data contained within it. I put on my designer hat and write about it in my design process journal

10. PSEC: Connecting Dots, Part I

With the draft design of a “task widget” completed, I have to convert it to HTML and style it so it looks right. I create a page template that draws three widgets using static HTML. Woo hoo!

My victory celebration is premature, however, because I realize that these widgets will have to be drawn dynamically in Javascript. That means I need to know what Javascript file to load for this specific page template. I hack together a way of doing it so any page template can load any file within the theme’s javascript code folder.

11. PSEC: Connecting Dots, Part II

I experiment with jQuery to bring my HTML widget to life, getting used to the selector and event binding syntax. I’m able to show/hide elements within each TaskWidget, and replace editable text with form text. It’s clear, though, that I need to look closer at Javascript as a language, and perhaps find a better reference for jQuery.

12. PSEC: Connecting Dots, Part III

Armed with two new books about jQuery and Javascript, I write a more sophisticated dynamic script loader. This allows me to include as many code files as I’d like without a lot of fuss, helping keeping everything modular for practical source control. I start thinking about how a Model-View-Controller (MVC) architecture will work in Javascript.

A review of Javascript as a language on Wikipedia provides additional insight; it’s very similar to Actionscript 1.0 in its use of objects. Scoping rules are different too.

13. PSEC: Connecting Dots, Part IV

It’s AJAX day, answering the question of how to get data from the server in a secure, user-based, authenticated manner. I also come across the challenge of “object relational mapping”: how do you “map” values in an object data structure to the tables in a relational database? It’s not a trivial problem.

After many hours of collecting information on the various ways to do an AJAX call with authentication, both with and without WordPress, I decide to sleep on it.

14. PSEC: Connecting Dots, Part V

The morning brings clarity. Although I am skeptical that using WordPress’ built-in AJAX handler is the best way to go, it is documented and it is worth trying first. Most of the tutorials I read, however, do not work with my particular theme-based (as opposed to plugin-based) implementation of AJAX.

I am forced to trace the WordPress source code line-by-line to find where the call is failing. As a bonus, I have a much firmer grasp of WordPress AJAX internals, which allows me to create my own solution. I have to rewrite some initialization code, but the result is tighter and better-structured.

At last, the ability to send data to the server and receive a response is mine. This is a significant step forward.

15. PSEC: Defining a Data Protocol

With the ability to send/receive data, I can get back to the task of loading data from the server and drawing it in the client browser window. To do that, I need to define a command protocol.

I expand my test cases from yesterday to send strings, integers, arrays, and objects round-trip. This verified, I then document a protocol with robustness, troubleshooting, and ease-of-implementation in mind. There are commands for loading, saving, adding, and deleting both the model (Tasks) and the view widgets (VTasks). I consider the data structures I will use for Model, View, and Controller.

At this point, I am ready to start writing the actual application.

16. PSEC: Implementing the Protocol

Oops, I spoke too soon. I have to actually implement a system for issuing commands to the server and receiving responses in return, all according to the new protocol.

I foresee the need for a “queued command” feature. Some commands may need to finish (saving, for example) before other server commands are allowed to execute. Since AJAX commands are asynchronous, this requires combining a master callback handler with a queue to serialize access to the server.

Now that the command system works, I can plug in the details of reading data from the SQL server and sending it to the client Javascript to put into its own local data structure. But that will have to wait until tomorrow.

17. PSEC: Simple Data Initialization from Server

Now, I have to fill-in the details of retrieving real data in terms of my application: Tasks, Actions, and their associated ID numbers. Not only do I need to be able to retrieve them from the server, I need to also store them on the client-side so I can draw that data to the screen.

18. PSEC: Rudimentary GUI, Part I

After getting data from the server, I now need to actually draw that data on the screen. That means I need to implement some kind of graphical user interface; up to now, everything has been invisible behind-the-scenes stuff.

At minimum, I need a create new task button, and a way of maintaining a list of tasks. A wrinkle is that whenever a new task is created, it has to be created on the server first. In Part I, I create the button and handle the behind-the-scenes task creation.

19. PSEC: Rudimentary GUI, Part II

Now that I can create a task on the server, the next step is to draw the task on the screen. This means writing some jQuery code that creates a new HTML node, then adds it to a DIV somewhere on the screen.

20. PSEC: Saving Data

How do I save data back to the database? I add a “Save” button that collects “dirtied” data and then sends it back to the server. It seems to work!

21. PSEC: Drag and Drop List Saving and Loading

Now that I can save stuff back to the server, I should also save the visual state, such as the order of tasks that are showing on the screen. I want to implement drag-and-drop sorting of the task list, which means that the order of tasks will no longer be by ascending taskID.