Navigation bar for Freud’s The Interpretation of Dreams
With Summer of Code midterm evaluations coming up, I realized I am probably very overdue for a blog post on my project. I’ve had two months to work on the “Improving support for book structures” project with Mediawiki, and it’s going well. As can probably be expected, the schedule that I’ve been following has been quite different from what I anticipated. When I proposed the project, I had envisioned modifying BookManager, an existing extension written by Raylton, one of my mentors. However, it quickly became clear that the entire design of the extension I’m creating is so different from BookManager that it makes more sense to just write a new extension. As such, I’m working on BookManagerv2, writing it from the ground up. This has changed my schedule a bit, in that I’m not just modifying existing code, but it also has given me more freedom, in that I don’t have to worry about maintaining (or accidentally breaking) existing code.
Raylton encouraged me to use Bugzilla, Wikimedia’s bug tracking system, to break the project into smaller pieces. We were allocated our very own Bugzilla component, where we have filed some 43 bugs already (and closed 21!). We also created a list to prioritize the bugs, which helps me focus on one issue at a time.
The first part of this project has centered on creating the JSON backend and creating what we’re calling the “reading interface”. I created the JSON schema, which outlines the properties of the JSON block. Each work has its own JSON block (see an example), which is validated against this schema. Currently, these JSON blocks have to be assembled by hand, but the next part of the project will be to create a frontend that allows users to enter information through a form, which will then create the JSON blocks. The reading interface consists primarily of automatically adding navigation bars to each section of the work, populating them from that work’s JSON block (see an example). These navigation bars have four components. The first is a metadata dropdown. Clicking on the “i” icon will show a dropdown that contains all of the work’s metadata: title, author, publication date, etc. The second is a chapter list dropdown. Clicking the list icon drops a list of all the chapters in the work, and from there, the user can navigate to any chapter or section. Works with many chapters have a scrollable list in the dropdown (see the chapterlist dropdown of this work). The third and fourth components are previous and next links—each navigation bar has a forward/back link to the preceding and following chapters, if they exist.
Creating these navigation bars has been really interesting, because I’ve encountered challenges I’ve never encountered before. I’ve never worked on a multi-language project, and so this is the first time I’ve had to consider localization. One of my mentors is constantly telling me when I’ve accidentally hardcoded English-language text into the extension—I’m so used to doing so that I don’t even notice it! I’ve also had to work on recognizing that just because something might load quickly and work well for me doesn’t mean it will for everyone else. Initially, each time the navigation bar was added to a page, the extension was querying for the contents of the JSON block. This works well for me, as I have a fast Internet connection. But it was pointed out to me that this might only increase slow loading times for other users, and so I added caching functionality.
So, this is where the extension stands now. I have a few more bugs to close up by July 31, and then I’ll move on to working on the “editing interface”: the form that allows users to enter the book metadata without having to write out the JSON block. Raylton and I have already begun filing bugs to sketch out the workflow for this section of the progress, and I’m looking forward to it. Then, on August 5, the “clean up stage” begins: I’ll focus primarily on testing, fixing bugs, and documenting the code.
I’m pleased with the progress I’ve made on this project, but I definitely learned a lot about planning projects like this. When I was formulating my proposal, I felt like the project wasn’t as ambitious as it should be—I felt like I should certainly be able to complete more than I was planning. Now that I’m actually working on it, I’m very glad that I kept the scope of the project small. If I had three months of pure code-writing, I probably could accomplish quite a lot more. But this project is so much more than just quietly writing code: it involves a lot of design discussion, planning, and researching. I’m working with an unfamiliar language, and with a very large, complex project, so I’m constantly asking questions about PHP and about how Mediawiki handles various things, from localization to caching.
If you’re looking for more frequent, specific updates than I provide on this blog, feel free to check out my weekly progress reports.