index-api.xqm

xquery version "3.1";
(:~
 : This module provides an API to retrieve index entries as a sequence for a
 : given page.
 :
 : @author Mathias Göbel
 : @version 1.0
 : @since 2.5.6
 : :)

module namespace index="https://fontane-nb.dariah.eu/indexapi";

declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
declare namespace tei="http://www.tei-c.org/ns/1.0";
declare namespace test="http://exist-db.org/xquery/xqsuite";
declare namespace xhtml="http://www.w3.org/1999/xhtml";

import module namespace rest="http://exquery.org/ns/restxq";
import module namespace config="http://textgrid.de/ns/SADE/config" at "../config/config.xqm";

declare variable $index:dataPath := "/db/sade-projects/textgrid/data/xml/data";

(:~
 : resolves and lists all references on a given page based on their index data
 :
 : @param $uri – A valid TextGrid Base-URI without prefix
 : @param $surface – a string to match a tei:surface/@n in the document
 : (use “-” as delimiter)
 : @return a list with all entries
 : @see http://localhost:8080/exist/restxq/fontane/index/16b00/62v
 : @see https://fontane-nb.dariah.eu/api/index/16b00/62v
 :  :)
declare
  %rest:GET
  %rest:path("fontane/index/{$uri}/{$surface}")
  %output:method("html")

  %test:name("entities per page")

  %test:args("16b00", "2v") (: return empty sequence on interleaf :)
  %test:assertEmpty

  %test:args("", "") (: return custom error INDEX-API1 :)
  %test:assertError("INDEX-API1")

  %test:args("16b00", "foo") (: return custom error INDEX-API2 :)
  %test:assertError("INDEX-API2")

  %test:args("16b00", "1r") (: return more then 10 entities :)
  %test:assertXPath("count($result//xhtml:li) gt 10")

  %test:args("16b00", "2r") (: return 4 groups :)
  %test:assertXPath("count($result) eq 4")

function index:entites-per-page($uri as xs:string, $surface as xs:string)
as element(xhtml:ul)* {
let $docpath := $index:dataPath || "/" || $uri || ".xml"
let $surface := tokenize($surface, "-")

(: test for document available :)
return
  if(not(doc-available($docpath)))
  then
    let $docsInDb := collection($index:dataPath)//tei:sourceDoc
        /replace(base-uri(), "\.xml|/|db|sade-projects|textgrid|data|xml", "")
        => string-join(", ")
    return
      error(QName("FONTANE", "INDEX-API1"), "Unable to resolve URI. Try one of " || $docsInDb || "." )
  else

let $doc := doc($docpath)
let $page := $doc//tei:surface[@n = $surface]

(: test for surface available :)
return if(not(exists($page)))
  then
    let $surfacesInDocument := $doc//tei:surface[@n]/string(@n)
        => string-join(", ")
    return
      error(QName("FONTANE", "INDEX-API2"), "tei:surface not found. Try one of " || $surfacesInDocument || "." )
else

(: test for entries before further processing :)
if(not(exists($page//tei:rs))) then () else

let $entities := $page//tei:rs/string(@ref) => distinct-values()
let $groups := $entities ! substring-before(., ":") => distinct-values()

for $group in $groups
let $translate := local:translate-prefix($group, (count($entities[substring-before(., ":") = $group]) gt 1) )
order by $translate
return
  element xhtml:ul {
    element xhtml:li {
      attribute class {"group", $group},
      $translate,
      element xhtml:ul {
        for $entity in $entities[substring-before(., ":") = $group]
        let $ref := substring-after($entity, ":")
        let $index := (collection($index:dataPath)/id($ref))[1]
        let $name := string($index/*[1])
        let $list := local:get-list-by-id($ref)
        let $href := "register-" || $list || ".html?e=" || $ref
        order by $name
        return
          element xhtml:li {
            attribute data-ref { $entity },
            attribute class { $index/local-name() },
            element xhtml:a {
              attribute href { $href },
              attribute target { "_blank" },
              $name
            }
          }
      }
    }
  }
};

(:~
 : Translate an index prefix into German.
 : @param $prefix a three letter code to resolve
 : @param $plural true when plural translation is required
 : @response the translation
 :   :)
declare function local:translate-prefix($prefix as xs:string, $plural as xs:boolean)
as xs:string {
if ($plural)
then
  switch ($prefix)
    case "eve" return "Ereignisse"
    case "psn" return "Personen"
    case "plc" return "Orte"
    case "org" return "Institutionen"
    case "wrk" return "Werke"
    default return "The prefix " || $prefix || " is not in the dictonary."
else
  switch ($prefix)
    case "eve" return "Ereignis"
    case "psn" return "Person"
    case "plc" return "Ort"
    case "org" return "Institution"
    case "wrk" return "Werk"
    default return "The prefix " || $prefix || " is not in the dictonary."
};

declare function local:get-list-by-id($id as xs:string)
as xs:string {
let $entity := collection($index:dataPath)/id($id)
let $test := if($entity[2]) then error(QName("FONTANE", "INDEX-API3"), "Entity »" || $id || "« has more then one occurence." ) else ()
return
    switch ( $entity/local-name() )
        case "event" return "listEvent"
        case "org" return "listOrg"
        case "place" return "listPlace"
        case "person" return
            if($entity/ancestor::tei:item)
            then local:get-list-by-id( $entity/ancestor::tei:item[last()]/string(@id) )
            else "listPerson"
        case "personGrp" return
            if($entity/ancestor::tei:item)
            then local:get-list-by-id( $entity/ancestor::tei:item[last()]/string(@id) )
            else "listPerson"
        default return
            let $list := ($entity/ancestor::tei:list[@type])[last()]
            return
                $list/local-name() || "-" || string($list/@type)
};

declare
  %rest:GET
  %rest:path("fontane/index/entity/{$id}")
  %output:method("html")
function index:rendered-entity($id as xs:string)
as element(xhtml:li)? {
    doc("/db/sade-projects/textgrid/data/xml/xhtml/index.xml")//xhtml:li[@id = $id]
};