One of the other issues we discussed was how to best teach “good” practices with JavaScript. The language constructs can get you in to a lot of hot water pretty quickly. You may have seen this, but a classic example of this is in the difference in the side Doug Crockford’s JavaScript: The Good Parts and David Flanagan’s JavaScript: The Definitive Guide.

This is a bit of an absurd comparison, but it does highlight that there is a big discrepancy in what JavaScript is capable of and what it is actually good at. There are just some things that JavaScript implements in a weird way. A crazy example of this is something like the following:

console.log(++[[]][+[]]+[+[]])

If you guessed this expression evaluates to 10, you are correct.

There are a variety of other pain points that are common in JavaScript applications; case sensitivity, hard line breaks (they are interpreted as as line-ending semi-colons), extra commas (IE has fits), global scope creep (e.g. hoisting), and issues with binding (e.g. a missing the this modifier). If you have developed much with JavaScript, you have most likely been bitten by several of these issues (hopefully not at the same time).

As we started planning the project out, we noticed that @dhh added support for CoffeeScript in the version of Rails (3.1+) we were targeting for the Praxis program. As part of the Asset Pipeline, Rails will automatically convert CoffeeScript to JavaScript, allowing you to write in a format that is closer to Ruby (with some pesky Python whitespace) that compiles to “good” JavaScript. Quite honestly, I wasn’t sure what to make of CoffeeScript when I first started looking at it. Unlike SASS which immediately changed the way I write CSS, I couldn’t imagine taking nearly a decade’s worth of knowledge for developing JavaScript for this crazy scripting language that just compiles down to what I’ve been writing, and I wasn’t alone with the other developers in the R&D group.

So what exactly was the turning point? Well, quite honestly after working with it a bit, I have to admit it has some nice features, but perhaps the biggest draw is the fact that it doesn’t require a big context switch in different modes of development. The other big draw is that the JavaScript that is generated is a better quality (uses the module pattern), has splats, comprehensions, takes care of scoping, the fat arrow (=>) can evaluate the ‘this‘ keyword properly for function binding, and the existential operator. There has been a lot of hype behind this, and Sam Stephenson (37Signals) made a great argument for using the language at the Future of Web Apps in London (2011).

Better JS with CoffeeScript – Sam Stephenson (37signals) from Louise Morgan on Vimeo.

Eric has walked the group through an introduction to JavaScript and CoffeeScript, and they seemed receptive to the idea of a language that compiles to JavaScript. So far, nothing has been written for the project in CoffeeScript, but I’m cautiously optimistic that the JavaScript that will drive most of the interactions will be a bit less buggy (and faster to develop) than it would had we targeted JavaScript for this project.

If you need even more incentive to take a look at CoffeeScript, be sure to take a look at Gary Bernhardt’s lightening talk from CodeMash 2012 entitled Wat.

I found some good documentation on moving installations of Omeka between servers, but I wanted to add some commentary to these instructions. Institutions might use these instructions and commentary when they wish to upgrade servers or change hosts for their Omeka sites.

First, install a new version of Omeka on your new server.
Carin and I needed to complete this step so we were sure we were using the latest version of Omeka. The steps for installing Omeka are well documented. I should note that several web hosting companies offer one-click installations of Omeka. This might a preferable option for information professionals lacking technical expertise.

Second, export your existing database file.
In a moment, we’re going to copy all of your files from your old server to your new server. Intuitively, you might think that the database file storing your collections would be moved along with those files. Unfortunately, that is not the case. Export your database file using these instructions.

Please note: these instructions don’t remind you that you need to update the host, user name, password, and database name fields in the database file before importing it into your new server. Make these changes.

Third, import your modified database into your new database on the new server.
You can import these database commands from phpMyAdmin or the command line. It is important to note that if you don’t change some of the information described above, your tables will still get created. Things will appear to be happening. This is not the case.Your database will not be able to talk to your new server.

Fourth, copy all of your files from your previous installation to a hard drive.
Get the FTP information for your old server (host name, user, and password.) Use an FTP program to copy these files. Preserve your file structure. Highlight your entire file directory for the site and copy it while preserving the file structure. Moving the files might take some time. (6 hours in my case!) Much of this time is taken by the archival quality image files. Don’t worry.

If your FTP program stops working in the middle of the transfer, don’t worry. You might have just disconnected from the Internet for a second. Alternately, some hosting companies throttle your connection if you’re taking up too much bandwidth. Just reconnect to your FTP program and restart the transfer where you started.

Fifth, copy the files on your hard drive to your new server.
Get the FTP information for your old server (host name, user, and password.) Highlight the entire file directory for the old site (stored on your hard drive) and copy it to the new site. Be sure to overwrite existing files and folders.

You now have made a copy of an Omeka installation on a new server. Your user names and passwords will be the same as for the previous installation.

Aside from reactivating plug ins and themes, the most prevalent problem I saw in this process were servers write-protecting the database file. This means that the file db.ini in the root directory will remain the default file despite you trying to overwrite it. There are many ways to fix this problem, but you can just delete the default db.ini file from your root directory and then transfer the db.ini from your hard drive.

Though Sarah and I have both freely admitted to our fetishization of deadlines, hard-and-fast deadlines seem to be rare in graduate school. It is not uncommon to ask for, and usually receive, extensions on research papers, even theses (though that involves quite a bit more hoop-jumping), and everyone knows at least one perpetually-dissertating Ph.D. I also don’t know many graduate students who can set rigid deadlines for themselves and adhere to them without fail.  I don’t mean to speak judgmentally of my own ilk, but as a species, humanities graduate students seem to be more comfortable with deadlines of a very flexible nature, and for good reason. Our research is often difficult to demarcate into stages, and hours of work are not easy to estimate because the material we examine is rarely quantitative.

I say all this to preface my surprise at the ease in which the Praxis team was collectively able to create and agree on a workplan, as well as at the relief most team members expressed once tasks were clearly assigned to dates on the whiteboard and to people in GitHub, which is what we’ll be using for workflow management. The readings on project management repeatedly emphasized the value of allowing those responsible for certain aspects of the project to set their own deadlines, and so far Sarah and I have been the only ones to push back a deadline we’ve set (for writing the About page prose, no less, which you would think would be easy for English grad students). The team has consistently met their deadlines and each specialized group has met to set even more specific goals for their work. Prism is coming along, at warp speed!

I’m beginning to see the efficacy of group workplans outside of Praxis, too, and this coincides with my earlier post about the possibilities for collaborative work available to graduate students who seek them. I am currently one of two representatives for Master’s students on the Graduate English Students Association board, and we’ve organized a thesis work group in response to a request at last semester’s department town hall meeting. I expected the group to be very lax, meeting biweekly to check in and sound off, but the group quickly decided to meet weekly, share work frequently, and set rigid deadlines; our task for this week’s meeting is to devise a thesis syllabus, a workplan for thesis research for the semester. I was not expecting this level of enthusiasm for deadlines and accountability from a room full of second-year MAs -  many of whom are distracted by job-hunting or, like me, the medieval torture chamber that is Ph.D. program admissions -  but even outside of DH projects, it seems that graduate students want  to work collaboratively because being accountable to a group, the joys and shames of having to report your successes and your failures to peers, can be a very powerful motivator.

My first experience using the plugin was last year for an Introduction to Digital Humanities course at UT-Austin’s School of Information taught by Tanya Clement (also our advisor for this project — she goes into more detail about the project background here). Dr. Clement asked us to create an Omeka exhibit for a set of correspondences, including images of the original letters as well as TEI documents of marked-up content. It sounds simple enough, but there was a lot of frustrated graduate student Facebook posting going on in the days before the project was due as people ran into unexpected technical difficulties.

Overall, there seem to be two main problems with the plugin. For the majority of the documents, we couldn’t get them to format at all – the entire body of text would wind up in one large paragraph in miniscule font at the top of the page. In a few other cases, the document would format enough to be readable, but it wouldn’t pick up the finer details of the TEI tags. For example, <p> tags would result in paragraph breaks, but <sic> and <corr> elements wouldn’t display– so something like “<choice><sic>sndstorms </sic><corr>sandstorms </corr></choice>” would show up as “sndstormssandstorms” in the body of the text. Though this seems like a relatively easy XSLT fix, we imagine other fixes (even possibly this one) may not be so straightforward.

Throughout the project, Zane and I will be documenting our work here at the Scholars’ Lab blog. At the end of the semester, we hope to provide not only an update to the plugin, but also user documentation, including use case scenarios and templates.

We’re going to be seeking input over the next few weeks on how this plugin would work in an ideal world, and we need your help! Look for a more formal survey soon, but in the meantime, let us know your thoughts in the comments – what are you looking for in a simple, out-of-the-box TEI display tool?

So far the tool I’m working with is the I18n gem which comes bundled with rails. The tool will make it easy for us to translate the interface. I18n so far seems very straightforward. I am creating YAML documents for each language. The YAML documents assign keys or placeholder names (kind of like variables) to all the strings that need to be translated in the views. Instead of writing strings directly in the views, we will write the placeholders. Depending on the locale that is selected, the placeholders will fetch the appropriate strings from the YAML files. Pretty simple! [crosses fingers nervously]. Besides the ability to abstract strings from their context, I18n also takes care of date and currency formats. Not that we will need the latter, though it’s nice to know we could make it all about the pesos if we wanted to.

Adding sample texts in French and Spanish remains a decision for the future, given our time constraints. I’m working as fast as I can to develop the i18n functionality, so that we do have time, but there is no guarantee. Stay tuned!

The collaboration makes sense on many levels, but here are two that surface readily:

1. These are complex technologies that function in a complex social and cultural system. We can meet the development needs because we represent institutions with different institutional missions, different (though like-minded) communities, with different resources.
2.  Our students, who will seek jobs in which they work collaboratively in different institutional missions, from the perspective of different (though like-minded) communities, with different resources, must be prepared to meet these challenges within a network of a the wider DH community.

If we believe in a basic DH tenet that making is a theoretically framed activity that helps deepen our understanding of our cultural artifacts and our modes of knowledge production, we must instill, as Bethany so aptly articulates, ”a can-do, maker’s ethos” in students who will feel “empowered to build and re-build the systems in which they and future students will operate.” To further this cause, we must also instill a second basic DH tenet in our community of scholars, makers, and teachers: we must pool our resources, both technical and academic, and develop our technologies (such as the TEI and Omeka) and mentor our students, together.

Both Carin and Zane will blog regularly in this space as the project develops. Onward ho, ya’ll.

I love lists almost as much as I love agendas and program management in general. Here is a status update in list form for you, Dear Reader. And Team, please feel free to expand/clarify/correct the following:

1. We have finalized the texts we’re going to be uploading into Prism for first-round users. Today, some of us tested a few of the suggested “highlighting” categories with help from our low-tech friends: transparencies, markers, and photocopies. Ed, Brooke, Annie, and I will be reviewing and revising categories over the next few days, and the entire Praxis team is invited to test our new suggestions this coming week.

2. The development team met their latest milestone goal: authentication and authorization for the Prism site is a go! User accounts! Ding!

3. As Lindsay notes, the wireframes (and thus, for the most part, the user story), are finalized. Design wizzes (plural of wiz?) Ed and Lindsay have been rocking out on the front-end work: Ed continues to wow us with his aesthetic brilliance (see his “striptease” post of Jan 26), while Lindsay works on making the dream a reality via CSS/HTML.

4. We’ve been inspired by the recent trend toward internationalizing Ruby on Rails applications, and have nominated the most Continental of our Fellows, Alex, to the position of Internationalization Expert(-to-be). I’m sure you’ll be hearing more from him about this exciting new development in the near future.

5. Finally, on a more personal note: I continue to enjoy how much time I get to spend with my colleagues while we work toward a common goal. Collaborative ventures certainly pose some challenges that would be non-issues in individual project contexts, but I think we’re all benefiting from learning how to work not only with digital tools but also with one another. The Fellows’ lounge was busy busy busy today–and that’s the way we like it!

Since I’m so new to HTML and CSS, I have no shame about asking for help with the smallest issues (like italicizing text) or with far-reaching errors (the whole page is the body?!), but I also have no shame about celebrating the smallest successes (rounded corners!). In addition to a few meetings with Jeremy, Ed’s great ideas and Illustrator skills and Annie and David’s HTML knowledge have helped me make progress. People are probably going to start sending me “Let me Google that for You” links pretty soon, but at least right now, I’m feeling warm and fuzzy and collaborative. On Monday morning, Brooke, Sarah, Jeremy, Ed, and I worked through the wireframes for Prism one more time. We had some drafts from the end of last semester, but some decisions about how the tool will work have affected how the site will look, so we revisited our wireframes and got them in good enough shape to present to the whole team on Tuesday. This picture shows what we came up with. It doesn’t look like much, but I think we all feel pretty accomplished now that we have a “clean” and simple form to design on.

The above video shows the visual options offered by the model of the deck prism.

While the deck prism is recognizable as an object, its clarity and sharp lines make it a good source of abstract imagery for the site. The model also allowed me to experiment with reflections of the texts we chose as our three highlighting samples. The text was simply applied to a plane directly below the prism in the 3D scene, and the reflections changed on the fly based on the camera position. You can see part of the first line from “The Raven” reflected in one of the images below.



Finally, the last image shows the highlighter “palette” that we used for our wireframe. The boxes are mostly just placeholders, but the colors represent some of the options that came out of the deck prism, and I think the categories we chose for Edgar Allan Poe”s “The Raven” could elicit a thought provoking response from a crowd.

*UPDATE: The position is now open to all qualified candidates.
Please note new URL below!

Senior Research Specialist, SCI

The Scholars’ Lab at the University of Virginia Library seeks a senior research specialist for a full-time, 18-month position with the Scholarly Communication Institute (SCI). The ideal candidate will have: excellent research, writing, and organizational skills; familiarity with humanities scholarship at the graduate level; and an interest in experimental approaches to digital authoring and publication or the education of emerging scholars and knowledge workers. Some travel is required, and there is a possibility of a work-from-home arrangement for a professional and thoroughly reliable candidate.

Reporting to UVa Library’s director of digital research and scholarship, the SCI research specialist will:

• help design, execute, and analyze a broad-based, anonymous survey of humanities professionals (together with the perceptions of their employers) to examine graduate-level preparation for so-called “alternative academic” careers (20%);
• attend and provide research support for three meetings and regular conference calls on new-model publishing and authoring environments, in order to take notes and help compile proceedings and recommendations (15%);
• attend and provide research support for two to three meetings centering on the reform of methodological training in the humanities, involving major humanities consortia, professional associations, and funders, to take notes and help compile proceedings and recommendations (15%);
• assist in research and organizational tasks related to the development and day-to-day operations of the Praxis Program at the University of Virginia Library, including the hosting of a gathering to foster inter-institutional collaboration on similar initiatives (20%);
• and perform other research and writing tasks as needed by SCI principals (10%).

The SCI research specialist will join a vibrant and dedicated community of faculty and staff at the Scholars’ Lab, and as such will be eligible for the self-directed “20% time” that all team members are granted to pursue professional development and their own (often collaborative) R&D projects. This is a grant-funded position with a salary of approximately $50k per annum and full benefits as a member of the managerial and professional staff of the University of Virginia. The position begins no later than March 1st, 2012 and extends no later than August 31st, 2013.

Experience and Education: Master’s degree or higher in fields related to humanities scholarship or information science. Demonstrated ability as a writer and researcher. Project management experience or experience with survey design and analysis desirable.

Please APPLY ONLINE.

Our next programming steps include building a user model and incorporating authentication and authorization (probably using CanCan and Devise ruby gems).  This will be more complicated that what we’ve produced so far, but we think that with the help of lots of screencasts and ruby gem documentation, we will persevere.

On other prism news, we will officially decide on our texts for Prism today in our meeting!  It’s all starting to take shape.

The most important product of our meeting was the project workplan timeline the team collectively created. I know that deadline-lovers Brooke and I feel six hundred times better about how the rest of this semester is going to proceed, but I think everybody is happier knowing exactly what needs to happen and when. I would only be exaggerating slightly to say that it was magical to watch the workplan take shape. Despite the fact that we’ve all been meeting weekly for an entire semester, as the project has progressed and the design team and programming team have been working more independently of one another, it has been difficult to see how everything fits together. But when we had to agree on deadlines for project milestones (when will we be able to display a text? when will user accounts be ready? when should the highlighting tool be functional?), designers and programmers had to engage in a dialogue about what each group would need from the other in order to meet these goals.

The meeting served as yet another reminder of how absolutely, impossibly lucky I am to be part of this program. As project managers, Brooke and I are ideally positioned to understand how the Praxis Program and our project Prism work as collaborative ventures. It is impossible for every member of the team to keep track of what each subgroup is doing at all times, but it is necessary that project managers do just that. I can’t wait to get my hands dirty! I’m sure I speak for both of us when I say that we are thrilled and honored by the trust our team has placed in us. We won’t let you down!

Brooke posted last week about seeking out ways to engage in collaborative work, and I want to point very quickly here to the Digital Humanities Summer Institute. I attended DHSI last summer, and it certainly didn’t disappoint on the collaborative front. Brooke and I are both making the trip to Victoria this summer, and I’m sure she will only find more evidence there of what she’s seen so far as a graduate student in the humanities: seek collaboration, and you shall find it. If you’ve never been but always wondered, I highly recommend that you make this the year you join the (collective) fun!

Saturday evening I had a chance to catch up with one of my early undergraduate mentors. He had questions. He wanted to know what I knew about the DH world. I’m sure half of his curiosity came out of an earnest desire to hear the tale of my travels. The other half was a shrewd (and responsible) move to build a vocabulary for conversations his department will inevitably have this year with the dean, other departments, the library, etc: Can an isolated DHer work well with limited resources? Do you need a center? How do you get graduate students involved? Our conversation went on for a good three hours and it was very rewarding to offer a candid assessment of the field from where I’m standing.

I also realized that where I’m standing is what in battle we would call higher ground. I don’t mean the privilege of hobnobbing with the enormous DH talent we have on grounds. Nothing, of the sort. Although projects are a whole different affair, you could develop decent DH skills and ideas were you connected from Pie Town. I mean the privilege of seeing graduate methods transformation first-hand. I agree with Brooke that there is a continuum that links us to analog models in the department (at least at UVa). But the continuum does eventually lead to new ground.

What I’ve seen, of course, has been well recorded here by all the Praxis bloggers. If this is your first time visiting our site and you are interested in the fresh air blowing our way, I encourage you to read more…

The readings were extremely helpful (see the “Intro to Project Management” section of Praxis topics for our short list of most helpful resources), especially Brian Croxall’s ”12 Basic Principles of Project Management” and Sharon Leon’s “Project Management for Humanists.” Both articles stress the PM’s need to assess the viability/sustainability of a project before it’s begun, the importance of a clear and flexible workplan that is derived collaboratively and realistically, and the PM’s responsibility to manage and encourage frequent communication amongst team members and partners. Both articles also begin with a point that has been made quite frequently, but that has not necessarily been my experience as a graduate student so far: that humanities graduate students are not trained to work collaboratively.

While I wholeheartedly agree with Leon, Croxall, and most of the DH community that graduate education must be transformed to formally, explicitly transmit this kind of training to humanities scholars, for the sake of the individual scholar and the profession as a whole, there are many opportunities to work collaboratively as a graduate student, but they must be sought out and are often extracurricular and small-scale. I recognize that it can be very easy to become the scholar/hermit in a graduate program, especially because programs have not yet adapted to encourage collaborative research in the traditional sense (like a tag-team digital dissertation), but collaboration on the most basic level has been ingrained in my daily experience in UVA’s English department – from discussion in grad seminars that leads to new research, to collaboratively editing papers and personal statements with peers and faculty mentors alike, to extracurricular activities like the Graduate English Students Association and its conference committee (groups that require quite a bit of PM-type skills).

This is not the kind of training Leon and Croxall are calling for, but my graduate education (so far) has trained me to seek out opportunities to collaborate with others within the department and outside of it (in my work with Praxis and IATH, for example). I have to stress that I do not disagree with the inadequacy of graduate methodological training; if I did, I wouldn’t be a Praxis Fellow. But I think we can find the basic principles for collaborative research happening already on a very small scale, and it’s up to graduate students to make collaborative research a priority – that is, to find those opportunities, seize them, and ask their programs to support them. Pardon the lengthy post; I know I’m not saying anything new here and I may be totally off-base, but I thought I’d respond with my experience as a nascent scholar and even-more-nascent member of the DH community.

Book Two of the Iliad notoriously contains a list of nearly 190 place names and includes the 29 contingents and that make up the Greek expedition to Troy.  Before launching into an over 250-line catalogue of the leaders of the Greek forces and the number of their ships, Homer appeals to the Muses to aid him in this tour-de-force of memory.  Without their help, he says:

I could not recount their numbers nor name them,
Not if I had ten tongues and ten mouths,
And an unbreakable voice and a brazen chest within,
If the Olympian Muses, daughters of aegis-bearing
Zeus, would remind me how many came under Ilium.

The Catalogue of Ships that follows this invocation can be mapped as an itinerary, or more precisely, three itineraries that traverse most of Greece.  The theoretical basis for the project I am undertaking with the Scholars’ Lab at the University of Virginia Library is already complete. In my recent book, Homer’s Trojan Theater (Cambridge University Press, 2011), I argue that Homer was able to recite the Catalogue by creating a mental journey that used the mnemonic techniques involving loci or places, well known from ancient rhetorical writers.  By envisioning a series of places, Homer could mentally walk – or sail – through Greece and produce a detailed catalogue. Our project will reproduce that journey by showing that the itinerary described follows the natural contours of Greek geography and the patterns of early Greek urban organization.

Mapping the Catalogue of Ships involves several steps.  “Least-cost path” GIS analysis by the Scholars Lab is revealing the terrain that must naturally be followed when taking a walking tour of the Greek mainland.  We are creating an interactive map that follows that path.  The Barrington Atlas of the Ancient World (2002) as well as the recent Historischer Atlas der antiken Welt (2007), The Homer Encyclopedia (2011) and the Pleiades Project, a collaborative database for ancient sites, have pinpointed locations for which we have evidence.  We will attempt to link the sites mentioned in Homer with archaeological material and useful bibliographies.  Finally, we hope to do in situ investigations by actually traversing the plotted itinerary at ground level to survey the terrain, and create extensive panoramic photography. Our main goal is to demonstrate that the arrangement of the Catalogue, far from a random list of place names, corresponds to the natural geography of Greece.  In cases where the position of a site is unknown or disputed, we hope that our analysis will provide plausible geographical and literary evidence to help identify its location.

Collaborators in this project include Ben Jasnow and Courtney Evans, two of my graduate students who worked with me on the Trojan Theater project and who are assisting with GIS analysis, under the guidance of Chris Gist and Kelly Johnston of the Scholars’ Lab. Wayne Graham and other members of the Scholars’ Lab R&D division are creating a presentational framework for our maps and text, and Jeremy Boggs is our lead designer.

Jenny Strauss Clay
William R. Kenan Jr. Professor of Classics

I think it’s brilliant the way that Praxis has been structured, with one training-intensive semester and the next semester spent – I’m assuming – in executing what we’ve been theorizing. That’s not to say that we haven’t done anything yet; we have produced the programming and design foundations for Prism that we will hammer down and build from in the months to come. There have been days in the grad lounge, though, when I’ve felt anxious about how much work there is left to do and how difficult it seems to reach concrete goals when our discussions usually raise more questions than they answer. But even if we spend our entire Tuesday mornings arguing/theorizing about what we think Prism should accomplish, our time isn’t wasted if it means Prism will be (1) a clearly designed tool (2) with a distinguishable thought process that (3) makes a specific intervention.

All of our discussions have addressed at least one of those three points without fail, so our mission in the months ahead is to channel our humanities-inspired zeal for theorizing into reaching the goals we set for Prism in September – mainly, that we want to produce a working, 1.0 version of Prism by the end of the academic year. To reach that final, rather intimidating endpoint, I’d like to suggest that the Praxis team begins the new semester by establishing (collaboratively, of course) some real, manageable, short-term goals for the coming weeks.

I’m beginning to recover from Winter Break Amnesia (I’m sure our first Praxis meeting tomorrow will quickly bring me back to reality), but I am looking forward to getting back to learning HTML and CSS, to our civilized theoretical arguments in the grad lounge, and to those glorious moments when we (with the help of the gurus) learn how to turn theory into praxis and bring Prism further into the light.

<input class="simple-fixture" type="text" />

This works fine, provided that the HTML your code is working on is relatively simple. In practice, though, most front-end applications that grow beyond a certain critical mass of complexity end up with JavaScript code that makes DOM touches on large, complex markup structures that can’t be so easily replicated independent of the application itself.

This issue started to rear its head as Neatline became more and more complex over the course of the last couple months. The Neatline front-end consists of well over 10,000 lines of JavaScript, which works on markup generated by about 20 templates and partials – it would be a frightful headache to have to manually create a library of testing fixtures for the whole application. And even if I took the time to build them all out by hand, I would be committing myself to a labor-intensive, open-ended maintenance task: Every time you make a change to a template, you have to remember to comb through all the files in the fixtures library and replicate the change. Over time – and especially as new developers start working on the project – there’s a high probability that the “real” HTML generated by the live application will start to diverge from your fixtures.

My search for a solution led me to this fantastic post from JB Steadman at Pivotal Labs. Basically, he describes a clever method for automatically generating a library of HTML fixtures that uses the server-side test suite as a staging environment that prepares, creates, and saves the markup emitted by the application. That way, your fixtures library can only ever be as old as the last time you ran your back-end test suite, which should be a many-times-daily affair. I was able to implement this pattern in the Omeka/Zend + PHPUnit ecosystem with little difficulty. (Details and code after the jump)

Basically, we do this:

1. Create a special controller in your application that exists solely for the purpose of rendering the templates (and combinations of templates) that are required by the JavaScript test suite;
2. Create a series of testing cases that issue requests to each of the actions in the fixtures controller, capture the responses, and write the generated HTML directly into the fixtures library.

How does this work in practice? Imagine you have a template called _records.php that looks like this:

<div id="container">
  <?php foreach $records as $record: ?>
    <h1><?php echo $record->title; ?></h1>
    <div><?php echo $record->description; ?></div>
  <?php endforeach; ?>
</div>

And when it’s rendered in the application, the final markup looks like this:

<div id="container">

    <h1>Record 1 Title</h1>
    <div>Description for record 1.</div>

    <h1>Record 2 Title</h1>
    <div>Description for record 2.</div>

</div>

So, the goal here is to create a controller action that populates the template with mock records objects and renders the markup, which can then be captured and saved by an integration “test” that we’ll write in just a minute (test in quotes, since we’re using PHPUnit not so much as a testing framework, but more just as a mechanism for automating requests). First, add a new controller class called FixturesController, and create an action that mocks any variables that need to get pushed into the template:

class YourPlugin_FixturesController extends Omeka_Controller_Action
{

    /**
     * Generate fixture for _records.php.
     *
     * @return void
     */
    public function recordsAction()
    {

        // Turn off the default Zend layout-discovery functionality.
        $this->_helper->viewRenderer->setNoRender(true);

        $record1 = (object) array(
          'title' => 'Record 1 Title',
          'description' => 'A description for record 1.'
        );

        $record2 = (object) array(
          'title' => 'Record 1 Title',
          'description' => 'A description for record 1.'
        );

        $records = array($record1, $record2);

        // Render.
        echo $this->view->partial('public/_records.php', array(
            'records' =>  $records
        ));

    }

}

Basically, we’re just stubbing out two artificial record objects (for simplicity, we add only the attributes that are used in the template) and directly render the template file as a “partial.” Note the call to setNoRender(true) – by default, Zend will try to automagically discover a template file with the same name as the controller action, but we’re just disabling that functionality since we want direct control over which templates get rendered and in what order.

Next, add a directory called “fixtures” in the /tests directory, and create a file called “FixtureBuilderTest.php” to house the integration test that will do the work of requesting the new controlled action, capturing the generated markup, and saving the result to the fixtures library.

This should look like this:

class YourPlugin_FixtureBuilderTest extends YourPlugin_Test_AppTestCase
{

    private static $path_to_fixtures = '../spec/javascripts/fixtures/';

    /**
     * Instantiate the helper class, install the plugins, get the database.
     *
     * @return void.
     */
    public function setUp()
    {

        // Set up the testing environment and plugin.
        parent::setUp();
        $this->setUpPlugin();

    }

    /**
     * Fixture builder for _records.php.
     *
     * @return void.
     */
    public function testBuildRecordsMarkup()
    {

        $fixture = fopen(self::$path_to_fixtures . '_records.html', 'w');

        $this->dispatch('your-plugin/fixtures/records');
        $response = $this->getResponse()->getBody('default');

        fwrite($fixture, $response);
        fclose($fixture);

    }

}

Note that you need to specify the location in the project directory structure that you want to save the fixtures to. In this case, I’m saving to the default location used by Jasmine, but you could point to anywhere in the filesystem relative to the AllTests.php runner file in /tests.

Make sure that the /fixtures directory is included in the test discoverer in AllTests.php, run phpunit, and your fresh-out-of-the-oven fixture should be saved off and ready for action! All that’s left to do now is load the fixture in your JavaScript test, run your code on the HTML, and start enumerating test cases. We use a testing framework called Jasmine in conjunction with a plugin called jasmine-jquery, which provides an easy way to load fixtures into the tests:

/*
 * Unit tests for the records Javascript.
 */

describe('Records', function() {

    var recordsContainer;

    beforeEach(function() {

        // Get the records markup.
        loadFixtures('_records.html');

        // Select the container div.
        browser = $('#container');

        // Instantiate your code.
        browser.recordsWidget();

    });

    // Now, the tests:

    describe('some class of behavior', function() {

        it('should do X', function() {
            expect(true).toEqual(true);
        });

    });

});