FrancoToile

GN, MH and I spent some time yesterday developing a model for the bookmarking system that will be in the new, eXist version of the FrancoToile site. After throwing around a few ideas, we've settled on this:

A "bookmark" is a reference to a single timestamp in a video. In addition to containing the video ID and the timestamp, a bookmark can also contain an optional comment. Each bookmark is stored in a separate XML document in the eXist database. A proposed sample looks like this:

<bookmark id="b3" videoId="fraq1" timestamp="00:05:35.55">
    <comment>Note the usage of 'dans' in this context.</comment>
</bookmark>

Notes on the bookmark attributes:

• @id is a unique, sequential ID, prefixed by "b", generated upon bookmark creation.
• @videoId is the ID of the video file.
• @timestamp is used rather than an utterance ID, so that a user can bookmark an exact moment in the video rather than a general utterance.

A bookmark can never be edited or deleted via the public website, only by someone with access to the database.

When a user adds a bookmark to a video, an AJAX call is made that stores the new document and, upon success, returns the new unique ID of that bookmark. The unique ID is then appended to the query string in the user's URL. This query string method is how bookmark "collections" are created: they're simply a series of bookmark IDs in the URL.

When a user "deletes" a bookmark, they are not, in fact, deleting it, just removing the ID from their collection URL. Similarly, when a user changes the order of the bookmarks, this simply changes the order of the IDs in the URL.

Since bookmarks can't be edited, if a user wants to edit a bookmark - for example, adding or changing a comment - a new bookmark is created to reflect these changes and added to the user's URL. The original bookmark is then removed from the URL.

So, every action related to manipulating bookmarks results in a change to the URL the user used to access the video. When a user clicks on the "save my bookmarks" link, they are simply given the URL, which they can then share with others.

Note to self: when working in XQuery/eXist and having trouble with XPath queries, check for "default namespace" declaration at the top of the document and modify the XPath accordingly. Remember that the default namespace will be applied to all elements in XPath queries in that document unless explicitly stated otherwise (or unless the default namespace is deleted).

Remember the comma operator when returning a sequence of multiple elements in an XQuery return statement. If you want to return more than one element, then you need to wrap the whole thing in parentheses and separate each element with a comma. Compare the first "if" return with the second "else" return:

<div id="relatedList">
            {
            let $relatedCount := count($relatedNationality)
            return
                if ($relatedCount < 1) then
                <h2>There are no other people from {$nationality}.</h2>
                else
                (<h2>Other people from {$nationality}.</h2>,
                <ul>
                {
                for $related in $relatedNationality
                    let $relatedId := $related/@xml:id
                    let $relatedTitle := $related//tei:title
                    return
                        <li>
                            <a href="player.xql?id={$relatedId}">
                                <img src="images/thumbs/{$relatedId}.png" alt="{$relatedTitle}"/>
                                <span class="relatedListItemLine">{$relatedTitle}</span>
                            </a>
                        </li>
                }
                </ul>)
            }         
        </div>

A quick way to select a series of elements in an XSL transformation for-each-group, in case something like XPath's distinct-values function isn't sufficient (for example, when you want to group a series of elements by a certain value but you still want to access all of the other nodes in the elements):

<?xml version="1.0" encoding="UTF-8"?>
<markers xsl:version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:tei="http://www.tei-c.org/ns/1.0">
    <xsl:for-each-group select=".//tei:teiHeader" group-by=".//tei:nationality/text()">
        <xsl:variable name="nationality" select=".//tei:nationality/text()"/>
        <xsl:variable name="geotags" select="normalize-space(.//tei:geo/text())"/>
        <xsl:variable name="lat" select="substring-before($geotags, ' ')"/>
        <xsl:variable name="lng" select="substring-after($geotags, ' ')"/>
        <xsl:element name="marker">
            <xsl:attribute name="name" select="$nationality"/>
            <xsl:attribute name="address" select="$nationality"/>
            <xsl:attribute name="lat" select="$lat"/>
            <xsl:attribute name="lng" select="$lng"/>
        </xsl:element>
    </xsl:for-each-group>
</markers>

Added <geo> elements containing latitude and longitude for all the videos so that they can be efficiently mapped without having to resort to on-the-fly geotagging. As per the TEI schema I used the <geoDecl> element within <encodingDesc>.

To look up the latitude and longitude of each location, I used this tool: http://universimmedia.pagesperso-orange.fr/geo/loc.htm

Had to change includes/xslt/player.xsl to use the new "trait" element instead of "persTrait".

The FrancoToile RNG schema needs to be updated to include latitude and longitude information, so I generated a new schema from the TEI Roma application ( http://www.tei-c.org/Roma/ ). It turns out that a small handful of the conventions used in the FrancoToile data files are no longer valid, namely: date/@value is now date/@when persTrait is now trait dateline needs to be within a closer element So, I've fixed these issues in the data files, which now valid against the new schema. And, now that the schema contains support for latitude/longitude, those values can be added.

To use the HTML5 doctype ("<!DOCTYPE html>") with an eXist app, your exist:serialize string needs to look something like this:

declare option exist:serialize "method=html5 media-type=application/xhtml+xml encoding=utf-8 indent=yes doctype-public=''";

The important bits are the method and doctype-public options. Without both of those set, the doctype will not output properly.

Be careful using the "//" axis to iterate over a set of elements in a document fragment, since it doesn't work as you may expect. Take this XML, which I'll call $summary:

<p>
<span class="previous">... sens français, </span>
<span class="hi">francophone</span>
<span class="following"> également, mais quelquefois je me s ...</span>
</p>
<p>
<span class="previous">... ment, mais quelquefois je me sens plus </span>
<span class="hi">francophone</span>
<span class="following"> que français ...</span>
</p>
<p>
<span class="previous">... je ... je crois que notre culture </span>
<span class="hi">francophone</span>
<span class="following"> hein .. ...</span>
</p>

To loop through the "p" elements, you cannot use $summary//p since this is a document fragment. The <p> elements do not have a root element to which they belong, thus $summary//p has no proper context to find the 'child' <p> elements in $summary. Instead, use either the descendant-or-self or the self axis to loop through elements in such a fragment:

for $item in $summary/descendant-or-self::p
...

If you want to use the KWIC module and specifically the kwic:summarize() function when performing full-text queries on your eXist databases, ensure that, if you have a default namespace declared, you negate that namespace in your <config> element:

declare default element namespace "http://www.tei-c.org/ns/1.0";
import module namespace kwic="http://exist-db.org/xquery/kwic";
for $result in collection('/db/francotoile/data')//tei:TEI/tei:text/tei:body[ft:query(.,"francophone")]

order by ft:score($result) descending
return
kwic:summarize($result, <config xmlns="" width="40"/>)

Note the xmlns="" attribute on the config element. Otherwise, kwic:summarize interprets the element as tei:config and throws an error.