Welcome to the infinite-ulysses-dissertation repository!
#Repository Contents: Top-Level Folders
- About the Project (manifest of work units and rationale, description of formats in final submissions to the dissertation committee and registrar, discussion of project scope)
- The Code (code allowing Infinite Ulysses’ interface look and behavior)
- Technical Instructions (notes on syncing multiple repos, how to install and configure annotation functionality on Drupal)
- Miscellaneous (affinity wall photos, prospectus, screenshots, site content exports, official IRB waiver, other miscellaneous files)
#Table of Contents
What’s Infinite Ulysses?
This repo contains the code I created, modified, or otherwise built off to make the Infinite Ulysses digital edition. Check out this quick 3-minute video about the project to learn more about the site and the resarch project behind it:
This repo will eventually offer Drupal modules, site theming, documentation, and an installation profile to quickly pop up your own participatory digital edition.
Infinite Ulysses is a dissertational project of designing, building, and user-testing a “participatory digital edition” of James Joyce’s difficult but unbelievably rewarding novel Ulysses—a website where you can read the novel, annotate it (highlight words in the text and add comments on them) to ask questions, provide answers and interpretations and definitions, and otherwise collaboratively explore and enrich the novel. Infinite Ulysses builds off of a ton of great FOSS (free and open-source) coding work focusing around the “Annotator.js” tool (see the Provenance section for more specific credits), with a focus on packaging these into a Drupal site where existing and custom social modules can act on the annotations (ranking them, tagging them, curating them, etc.). Check out my research blog literaturegeek.com for regular blogging on the project’s progress.
Milestones
Provenance of included code
Functionality
Annotator.js
Annotator.js is the foundation for the site’s highlight-and-annotate functionality. From the Annotator.js website: “Annotator is an open-source JavaScript library to easily add annotation functionality to any webpage. Annotations can have comments, tags, links, users, and more. Annotator is designed for easy extensibility so its a cinch to add a new feature or behaviour. Annotator also fosters an active developer community with contributors from four continents, building 3rd party plugins allowing the annotation of PDFs, EPUBs, videos, images, sound, and more… Annotator is developed by a wide range of contributors and supported by a number of organizations. Previous financial support was provided by the Shuttleworth Foundation and the Open Knowledge Foundation.”
Annotation Drupalization
The current Drupal modules allow Annotator.js to work on Drupal page elements and save to the Drupal database.
Initial configuration on a Drupal site is currently a bit involved. Tags can be added to annotations, but not saved/stored (they’re lost on page refresh). Admins can’t interact with the Annotation entity via the Field UI (not fieldable), among other issues with how annotations are set up as entities.
Better Annotation Drupalization
I’m currently using improved versions of these two modules, created by Michael Widner (@mwidner) of Stanford’s Lacuna Stories project and graciously shared with me (yay digital humanities community!). That code is not yet shared publicly, as the Lacuna Stories project has not yet made their code public (but plans to do so). Until that code is made public, it won’t appear in this repository.
Where I’ve made changes to Michael’s code, I’ll include a note in the repository that records my work without revealing his code.
Highlighted Anno(tation)s Module
“highlighted_annos” is a custom module I created to further modify the Annotator.js Drupalization for Infinite Ulysses’ needs; the module updates what annotations are displayed in a sidebar when you click on a particular instance of highlighted text.
By replacing the Annotator.js pop-up annotation display with a Views (Drupal SQL query module) block, I was able to alter both the design and functionality of the annotation feature (e.g. adding display of and interaction with a rating widget, commenting on annotations, tagging by users other than the annotation’s author with separation of “my tags” from “all tags” on a given annotation for the current logged-in user). I was also able to improve the display of annotations when there were multiple annotations for a given highlight, adding an option to sort displayed annotations by highest- or lowest-rated, oldest or newest date, or most commented-on.
The module includes three files:
- highlighted_annos.info file: Contains basic module metadata (e.g. Drupal version, author)
- highlighted_annos.js: A 22-line jQuery (a Javascript library) file; handles the user’s input (the “client side” code handling everything that happens in your browser before information is sent to my website’s server)
- highlighted_annos.module file: A 67-line PHP file handling information once it’s passed from the “client side” to my website’s server. Accomplishes tasks including:
- structuring the form that takes as input the ID number (NID) of the annotation(s) related to the highlight the user clicked
- get that input and convert it into a format that works in a database query (“database, please find only those annotations matching these ID numbers and then return some specific information about each annotation”)
- prevent the webpage from redirecting when clicking on a highlight triggers the inputting of the related annotation IDs to the invisible form
Peter Schuelke’s post was especially helpful in creating this module.
This module is dependent on changes I made to Annotator.js (see below).
My Modifications of Annotator.js
Annotator.js is the foundation for the site’s highlight-and-annotate functionality; it lets you highlight text and add an annotation to it. See this section of this repo’s README for more on what Annotator.js does and who was responsible for what parts of its functionality.
I committed the original Annotator.js library files, then made my next commit hold all my changes (up to 2/6/2015); this will allow you to see a nice comparison of modifications I made to the Annotator.js library by visiting this commit page. Note that I may have made changes to these files subsequent to that commit (e.g. tidying things up a bit when time allows), but the most important code changes are visible in that commit.
Annotator.min.css
Use of the Mac FileMerge file comparison tool shows I made 21 changes to this CSS file, including changing the mouse cursor to a hand when hovering over a highlight, browser prefixes (required to make certain browsers use a CSS rule; e.g. -moz, -webkit), removing a lot of unneeded elements (e.g. gradients on the annotation filter buttons), and most importantly removing display of the Annotator.js viewer (a pop-up that I replaced with my annotation sidebar).
Annotator-full.min.js
Use of the Mac FileMerge file comparison tool shows I made 25 changes to this Javascript file. Many of the key modifications are marked with a comment (// or /* */) and the word “Amanda”, usually followed by a short explanation. The main reasons for modifying this file were small tweaks such as removing use of the Annotator.js Viewer (the pop-up for viewing existing annotations) in favor of my sidebar, and changing behavior from on mouse hover to on mouse click.
These were mostly one- or two-line changes; the biggest change is from lines 1847-1855, which I’ve commented on this page to make them easy to look at. This code reacts to a user clicking on a highlighted piece of text by *adding the ID numbers (NIDs)
*for all annotations referencing that highlight (i.e. the one or more annotations that might be associated with a highlighted piece of text)
*into a list (“array”),
*entering them into an invisible form field, and
*submitting that form.
This makes the list of annotations associated with a highlight available to the website’s server through my Highlighted Anno(tation)s module, described above.
My changes to Michael Widner’s Lacuna Stories code:
These were mostly small changes to text wording, although I did fix one site-breaking issue in the annotation.install file that Widner incorporated back into his code. You can find notes on what I changed in his code here, and I’ll share the full code once it’s been released.
Other Drupal modules
These are linked to their information pages on Drupal.org; you can read about the latest code contributors to each there.
Modules I’ve made tiny customizations to: (e.g. applying a patch that hasn’t been rolled into the current release yet; modules/custom)
**Modules I’m using as packaged (modules/contrib)
Installed and configured around 50 modules over the course of working on the current Drupal site; kept about 20 on the current site.
Appearance
- Custom child theme built off the Drupal Bootstrap theme framework (using Kalatheme)
- Drupal layout modules: Panoply, Radix, Panels
*Flat UI kit by Designmodo
- CC-BY vector graphics for the front page and annotation upvoting function:
The Text
Typographical formatting, proofing and error correction, and data formatting on the digital text of Ulysses. This site builds off the digital plaintext transcription of the 1922 first printing of Ulysses, transcribed by Matthew Kochis and Patrick Belk with the Modernist Versions Project (MVP) and offered for public reuse by the MVP under a CC BY SA license. I’ve added corrections to errors I located in that digital transcription, used regular expressions to reintroduce some basic formatting (e.g. indent and em dash before lines of dialogue), and manually am adding HTML/CSS as I read through the text to reintroduce extremely important typographical choices used in the 1922 first printing of the novel (as verified against the Modernist Versions Project’s digital images of the printing; decisions such as the all-caps headlines in the Aeolus episode).
The most up-to-date list of textual corrections can be found on the Text page on Infinite Ulysses. I’ve also created a public repository offering the text of Ulysses as HTML files (with my added typographical formatting and error correction) and files suitable for import into a Drual site (CSVs and .import/.export files).
Support credits
- The Maryland Institute for Technology in the Humanities (MITH) Winnemore Digital Dissertation Fellowship (2014-2015)
- Editing Modernism in Canada (EMiC) Doctoral Fellowship (2013-2014)
- University of Maryland English Department Summer Fellowship (2014)
- University of Maryland University Fellowship (2010-2013)
- Funding as a graduate research assistant and course instructor from the University of Maryland English Department (Summer 2011 and Winter 2012), iSchool (2010-2011), Digital Cultures and Creativity Honors College (Fall 2012), and MITH (Summer 2011-Winter 2013, Fall 2013-Spring 2014)
Analytics
- Crazy Egg (March 2015 only)
- Inspectlet (March 2015 only)
- Google Analytics (January 2015 onward)
I want to use this!
You can! That is, you will be able to, easily, once the code is polished and documented (and a piece of the code provided by a colleague is made public). I’m currently working on abstracting the code for use on otehr sites and drafting user-friendly documentation; Romantic Circles and the Shelley-Godwin Archive are testing this code out on development servers. Please contact me if you’re interested in using any part of this project on an existing site, or just want to play around with the code on a new site.
This is a dissertational project, and some of the work ater I’ve successfully defended will be packaging the code and creating user-friendly documentation so that others may make their own copy of the site (if that floats your boat) or otherwise mimic or build off this work. There will be many updates to the code over the next year (and beyond), as well as user-testing (both analysis and raw data to be made public). You may wish to check out my page on Infinite Ulysses IP & Copyright to understand what you can reuse (and how).
Documentation
This will eventually link you to resources to turn this repo into a participatory digital edition site of your own (probably over Summer 2015).
Issues queue
You’ll notice there’s already a bunch of items in this repo’s issue queue; I’m currently keeping most of my tasks private in Basecamp, but I’ll be moving any remaining tasks here after the public site release in June 2015.
You can submit issues to tell me about bugs on the site or feature requests, or otherwise contact me about the InfiniteUlysses.com part of my dissertation. You might notice issues get tagged with various labels—this helps me do things like prioritize work on anything blocking use/accessibility/inclusion on the site, or keep track of good suggestions and requests that I won’t have time to address during the scope of my dissertation. The “out of scope” label doesn’t mean your report isn’t useful—any feedback is useful! I’ll just only be able to do so much while trying to finish my PhD in 2015, which means data clean-up, analysis, and drafting a scholarly article on the project as well as trying to make it a better experience for our reading community. You can check out this page on the scope of my project to understand what I’ll be working on beforemy dissertation defense.
Caveat emptor: in-progress code
This is the public repo for code related to the Infinite Ulysses participatory digital edition, the focus of Amanda Visconti’s (@amandavisconti) digital humanities doctoral dissertation. Watch a quick 3-minute video or read more about Infinite Ulysses here or sign up to beta-test the site.
WARNING This repo represents code that is likely to be in-progress, outdated, insecure, strange, silly, or otherwise unwieldy, in an attempt to share the entire building process with the public. I don’t currently recommend using any of it, and I cannot currently provide assistance with using any of this code. Please wait for Summer 2015, when I’ll provide friendly documentation on creating your own participatory digital edition and also abstract the code from Infinite Ulysses to be used with any text.
If you’d like to be notified when an easy-to-use code+documentation package is available, please use the sign up form here and indicate your interest in the comments.
评论