Client
From Fisheye
Contents |
Notes
The client is responsible for querying criticisms applicable to a page, and for embedding that data into the page.
There may end up being more than one client implementation.
There are a few obvious options:
- A proxy. Either set up by user in browser preferences, or use a browse-in-a-frame scheme which redirects all links through a proxy. The great benefit of this is that one implementation could work with any browser.
- A browser plugin. Written again a specific browser. Firefox is an obvious choice due to its open source nature and the fact that plugins are encouraged. It might be possible to implement Fisheye client on top of an existing FireFox plugin - GreaseMonkey is a plugin specifically meant for modifying web pages as they are loaded, allowing for things like fixing broken links, changing CSS options on the fly, excising ads, etc.
- Any other options?
Various references, systems which modify or embed data in web pages:
- Greasemonkey FireFox plugin, and the many available scripts for certain pages
- Adwords on many free sites - often double-underlined words with popup ads
- Link preview popups - some companies pop up mini screenshots of web sitess
- Google cached search results - uses text block highlighting
- Google Maps' popup info boxes
- Flickr lets user mark sections of photos and link comments to em
Annozilla
Minumum to change Annozilla to Fisheye client:
- Change "view icon" in-page rendering to highlight text, icon mouseover gives popup for info ala mockup
- Way to minimize or hide sidebar but still have notes autoload
- Extend RDF schema for Fisheye-specific elements
- Replace RDF schema (search for "annotation-ns", in nsRemoteAnnotationServer.js, probably local server code possible elsewhere)
- We are assuming server can handle arbitrary schema
- Extend sidebar to support extended elements when submitting
- Update render option to put full fisheye info in box
Developing Annozilla
Geoff is using Linux. Anon cvs checkout code following instructions on Annozilla site. I had to install perl-archive-zip, then "make" in src/ dir works. annozilla-latest.xpi is created in downloads/dir.
Install
xpointerlib 0.2.4 from annozilla site annotations 0.4.0.a.2 from downloads/ dir annozilla-latest from downloads dir from CVS
note: to get xpointerlib 0.2.4 I had to install latest stable Annozilla from website, then uninstall annotations and annozilla.
Annozilla Code Notes
There was a mention that the code had been refactored for extensibility. Indeed, there seemed to be a lot of objects and prototype functions. However there are plans to refactor as MCV to make it easier to extend. Hopefully Fisheye can be implemented by deriving from the defined classes, in an extension which depends on Annozilla.
everything useful lives in src/content/annozilla/
the user interface code lives in src/content/annozilla/*.xul tried to match XUL to interface, but grepping turned up nothing in *.xul found strings in dtd files under locale/ to support i18n
grep "Annotation List" **/*.dtd
src/locale/en-US/annozilla/annozilla.dtd:<!ENTITY annotationAnnotationList "Annotation List">
grep annotationAnnotationList **/*.xul
src/content/annozilla/annozilla.xul: <treecol id="headerXUL" label="&annotationAnnotationList;" flex="1" primary="true"/>
Changing behaviour of icons: IconManager class seems responsible not for loading sets of icons, but for all in-page rendering. Function _insertIconBefore adds an eventListener for "click" to call iconClick() function for the corresponding annotation. Simple to change it to call a different function on mouseover.
Maybe needs to be a displaytype class/interface to allow for more flexible extension.
annozilla.js: main code behind each instance of the plugin. One Annozilla object, gAnnozilla, for each plugin instance.
Annotation types defined here: Annozilla.TYPE_NS = "http://www.w3.org/2000/10/annotationType#";
presumably Annotools overrides this?
userLoadOnCommand calls loadAnnotations(currentURI)
loadAnnotationsOnSuccess is called after auto or explicit load request returns. fires off _processAnnotationsWithAutoLoadInfo. each annotation gets added to both currentAnnotationsBatch and this.annotations. addAnnotations is then called with the batch. a timer is used to call _addNext for each. here the corresponding xptr is resolved, and the note/range pair registered with this.icons (for in-text markup) and the sidebar.
annozilla.xul: user interface definitions including sidebar
gAnnozillaSidebar.userLoadOnCommand() corresponds to "load" button. calls annozilla.userLoadOnCommand()
sidebar.js: code interfacing with sidebar widgets.
IconManager.js: handles page decorations such as icons and highlighting. At some point spans are inserted into the document, with the attribute "annotation-id". These add the highlights.
_insertIconBefore takes an icon element and uses _insertNode() to insert it into the document at end of range. also registers "click" event callback.
_insertAnnotationBefore creates highlight and/or preceding icon for annotation and embeds it in page
_getIconURI maps annotation types to image resource
primary external access seems to be when annozilla.js:_addNext calls addAnnotation, which calls the appropriate functions to add corresponding decoration
XBLhighlight.js: almost generic highlight implementation at the document level. addStyleSheet inserts the css needed to render.
XBLIconManager.js: assume this is the same for icons
globalOverlay.js: registers "load" listener to start Annozilla service
contextMenu.js': hook to be able to right-click on text and have popup non-modal add annotation dialogue
Fisheye requirements of rewritten Annozilla
What Fisheye and similar projects would need to build on Annozilla. Some may be already possible, some might be handled independently by Fisheye. Many items in common with TODO list.
- Fisheye can be standalone plugin with dependency against annozilla, or compiled with it, without maintaining patch against source
- Override (others might want to extend) list of annotation types
- handle subtypes?
- Add new RDF metadata to annotations, EG enumerated fields such as subject, open fields such as reference URI
- Extend annotation entry/edit dialogue and display to support new metadata
- Submit metadata to server, load from server, have access from render functions
- Provide custom icons, flexible enough to allow icon sets to be switched out while running
- Add or extend in-page decoration code
- Add a mouseover hook to the existing icon/highlight code
- Special rendering for special annotation types, EG numerical ratings (this example could be handled in image lookup, better example?)
- filtering out annotations by metadata according to user config
- Seperate config area preloaded with our server info (probably have independent config, want to extend existing config widgetry)
Annotools
[url=http://infolab.umdnj.edu/annozilla Annotools] is a customized version of Annozilla. Includes split-screen footnote display mode, customized RDF, toolbar. This is the best guide for how to extend Annozilla. For the first version of Firefox Fisheye client, we probably want to pull in the code which hooks into Annozilla framework.
Annozilla list emails
Inquiring to dev list as to extending annozilla, got the following useful information. See the [url=http://mozdev.org/pipermail/annozilla/2007-February/thread.html Archive] and thread "Extending Annozilla for a specific purpose".
Notes from first response below:
> Geoff Matters wrote: > I'm working on a narrowly targetted application of web
Well, I've been working on some Annozilla extension extension(s), working from the latest experimental development branch, see [url=http://annozilla.mozdev.org/ReleaseNotes.html Release Notes], [url=http://annozilla.mozdev.org/ToDo.html Annozilla TODO], as well as my patch page [url=http://infolab.umdnj.edu/annozilla Annotools]
> I expect to extend/derive the RDF schema to add data
> specific to this application, change annozilla to
What specifically did you have in mind? just go with casino spellen
> subimit/display the data, change the rendering, and
The new highlighting feature inserts spans for each annotation into the document (in the browser), with attributes that reflect their class, as well as a link to the default CSS file: ...chrome/content/annozilla/anotations.css. (see the header of this file for a few more notes).
We've been playing some games having the IconManger look for shadow CSS files and whatnot, but I think the consensus is to just have [extension-]extensions dynamically change the CSS link if they want to. I've started using "page" annotations to store such preferences for the annotated file that my extension can then process dynamically.
> Is there a guide for writing extensions which build on
Not yet.. maybe we can start one, perhaps based on your upcoming experience. Maybe we should start a documentation Wiki? [Matthew: What do you think? If so, where? I just set up a few for my own purposes, it was pretty easy; I could host another if desired.]
> annozilla? Is there an example of an extension
> extending annozilla? A suggested framework
My extension(s) [which I've started calling Annotool, by the way], might eventually serve as an example, but's not quite ready for prime time yet. The primary functionality includes a "footnote" style display, a handy configurable drop-down menu button (for the toolbar pallette), loadable tag sets (potentially RDF)... I've also been messing with multiple local datasources, potentially importing/exporting/uploading/downloading annotations...
The approach I've taken to extending Annozilla basically involves
- (1) operating on the spans/icons Annozilla inserts into the DOM, whose attributes include annotation-id's that allow retrieval of the corresponding annotation, and
- (2) using observers to respond to server/update events; Regarding the observers, (this may be more than you want to know at present) as things are currently set up, the annotation server component expects observers to handle nearly a dozen different function calls - it might be nice if it would more gracefully when observers don't have all of them implemented...
- (3) a few interface functions to invoke the editor, or post new annotations (eg. I added a "non-modal" post function, which should probably be renamed to something like PostAnnotationWithoutEditing)
Hope that helps, ...Greg
Other code references
[url=http://www.alistapart.com/articles/cssmaps Accessible CSS Maps] is at least an example of how to script popup info windows. It also discusses inserting popup data into a page in such a way that it is accessible by keyboard and to the blind.
Big questions
Does the server code need to be adjusted at all to handle different annotation types? Does the RDF need to be configured on server?
