diff --git a/README.md b/README.md index f9f8f5b5..a09379b8 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,19 @@ An extensible framework for digital Editions for the [eXist XML database](https: This framework still lacks a good name. If you have an idea, please let me know! +## Incompatible changes + +Release 24Q1 dropped support for METS-based projects. As METS files can have a number of very different ways of encoding +information, especially when it comes to behaviours, native support is hard to achieve. At the same time, most +installations use wdb+’s native wdbmeta system as this is what the admin functions work with. +If you require METS support, please open an issue and provide an example of your METS files. We will then try to create +import and export functions. + +Release 24Q1 introduced changes to the transformation: previously, XIncludes were not expanded before the XSLT was +applied to a file. This has now been dropped meaning that XIncludes will always be expanded. This is most likely the +expected behaviour. If you want to ignore XInclude, you can add this as a global setting in eXist: in +`${eXist-dir}/etc/conf.xml` set `serializer/@enable-xinclude` to `no`. + ## Installation You need a working instance of eXist (4.0 or later). It is recommended that you use the default software selection during installation. The default memory settings usually work very well but you can, of course, always give eXist a @@ -12,38 +25,10 @@ little more RAM. 1. Clone this repo including its submodules (xstring, wdbmeta) 1. `cd edoc` 1. run `ant` -1. install the `.xar` file created in `edoc/build/` using eXist's dashboard +1. install the `.xar` file created in `edoc/build/` using eXist's dashboard or (https://github.com/eXist-db/xst)[XST] The app will be installed into `/db/apps/edoc`. -### eXgit -Additionally, it is possible to use [eXgit](https://github.com/dariok/exgit) to clone the current version directly into a running eXist instance. - -1. Install eXgit as stated in the repo. -1. create a user `wdb` and a group `wdbusers` for the framework and log in under that name –– CAVEAT: this user, at least for the duration of the installation, **needs to be** in the **dba** group! -1. create the target collection (default would be `/db/apps/edoc`) as this user -1. open eXide from eXist's Dashboard -1. paste: - ``` - xquery version "3.1"; - - import module namespace exgit="http://exist-db.org/xquery/exgit" at "java:org.exist.xquery.modules.exgit.Exgit"; - - let $whereToClone := "/home/user/git/wdbplus" - let $targetCollection := "/db/apps/edoc" - - let $cl := exgit:clone("https://github.com/dariok/wdbplus", $whereToClone) - let $ie := exgit:import($whereToClone || "/edoc", $targetCollection) - let $ic := exgit:import($whereToClone || "/edoc/config", "/db/system/config/db/apps") - ``` -1. replace the value of `$whereToClone` with the full target directory on your file system where the app shall be cloned into -1. if you do not want to install into `/db/apps/edoc`, change the value of `$targetCollection` to the full DB path -1. run the script -1. open `post-install.xql` in your target collection -1. if you did not install into `/db/apps/edoc`, change `$targetCollection` accordingly -1. run `post-install.xql` to set rights and index configuration - - ### manual installation 1. clone this repo including its submodules 1. put folder `edoc` anywhere you want in your eXist; the default would be `/db/apps/edoc`; you can also rename it to your needs (in this case, you have to adjust the paths in the next steps!). @@ -55,7 +40,14 @@ Set the name for the instance and other settings in `edoc/config.xml` or using t ## Creating and uploading projects While many different ways of putting data into the application are possible, the standard way is to have one collection -under data for each project. It is possible to create an initial setup using `admin/admin.html`. The following describes a manual installation and assumes that you work with a standard setup, i.e. have installed the app +under data for each project. + +### Using admin functions +It is possible to create an initial setup using `admin/admin.html`. After creating a project, you can immediately start +uploading files using the upload form. wdb+ will take care of creating meta data entries. + +### Manual approach +The following describes a manual installation and assumes that you work with a standard setup, i.e. have installed the app into `/db/apps/edoc` and want to put your projects into `/db/apps/edoc/data/yourproject`. 1. create `wdbmeta.xml` in `/db/apps/edoc/data/yourproject`, either by copying, pasting and editing the example below or by using @@ -102,6 +94,7 @@ See the Wiki for details! * Repertotium frühneuzeitlicher Rechtsquellen * Protokolle der Sitzungen der Gesamtakadmie * Akademie der Wissenschaften, Heidelberg - * Theologenbriefwechsel + * Theologenbriefwechsel +* ULB Darmstadt If you use wdbplus for your editions, please drop me a message so I can add you to this list. diff --git a/doc/Basic-collection-structure.md b/doc/Basic-collection-structure.md deleted file mode 100644 index 63fa11b0..00000000 --- a/doc/Basic-collection-structure.md +++ /dev/null @@ -1,80 +0,0 @@ -## Intro - -While the app was built with the possibility in mind to adapt it to different local needs and data structures, there is a default structure. While the app tries hard to figure out the correct structure by itself, this may fail. If you use a structure different from the default, you may need to adapt several scripts and keep that in mind when updating and upgrading. - -## Default Structure - -The default setup install the app into the collection `/db/apps/edoc` of eXist. It contains the [[main HTML files|main-html-files]] and the everything else the app needs to run. It is also home to several subcollections: - - edoc - ├─admin - ├─data - ├─global - ├─include - ├─modules - ├─resources - ├─rest - ├─schema - ├─templates - ├─(annotations) - ├─(doc) - -* `admin`, as the name suggests, contains a few scripts to help admins keep an overview of the projects within this installation (more are to be added in later versions). -* `data` is where the different projects go as subcollections. While it can be empty, it may contain [[start.xml|main-files#start]] and should contain [[wdbmeta.xml]] to give a global start page or set global metadata. -* `global` is where globally available or root level content is stored, e.g. `index.html`. **This is the only place in the app root where users should (and need to) make changes** -* `include` contains recent versions of related projects, namely the schema for [[wdbmeta.xml|main-files#wdbmeta]] and a collection of XSL/XQuery functions to deal with strings (extending the normal XPath string functions). -* `modules` is where the main global scripts go. -* `resources` contains global resources such as default XSLTs, global CSS and JavaScript. -* `rest` contains scripts for the RESTful interface. While it is possible for users to change these scripts, it is recommended to instead add scripts instead of changing existing ones. -* `schema` contains schema files for global files other than `wdbmeta.xml` (currently, this is only `config.xml`). -* `templates` contains the rump HTML files used for the templating system. While it is possible to change these files, most changes can better be done by using [[project specific layout and functions|project-specifics]]. The standard files here may be overwritten by an update. -* `annotation` and `doc` are not in use yet but are to be considered 'reserved' as they will be used for internal functions in upcoming releases. - -Except for `global`, there are no user servicable parts in these collections. All changes may be overwritten by an update or upgrade. Instead, use the [[configuration options|global-configuration]] and [[project specific layout and functions|project-specifics]] to adapt functions and layout to your needs. -Should you really require a change in one of these subcollections, consider opening an issue instead so this can be changed to an option that can be set on a project or instance level. - -## Non-default structures - -### projects as subcollections of `edoc` -It is possible to deviate from the general structure. For instance, one might want to forego the `data` subcollection and store all projects as a subcollection within `edoc` itself. This is possible and should be recognized correctly by all scripts; however, as the main call to view a page is via `view.html` and an ID, this is not strictly necessary. Should you need it e.g. to maintain a stable URL for the source XML/XSLT/etc. files, consider using a reverse proxy instead, especially if you run into problems reading and displaying files. - -### different name than `edoc` -It is also possible to name the collection other than `edoc`. In fact, this feature will be put to use in a later release as part of the possibility to have both _publication_ and _workbench_ [[roles|server-roles]] run on the same eXist server. All scripts should be able to figure out the correct name. - -### as a subcollection of `db` instead of `/db/apps` -This is possible, too, and should not require additional changes. If you run into problems with the URLs generated by the scripts, automatic resolution of the basic URL might have failed. Consider setting the appropriate option in [[config.xml|global-configuration]] - -### port 80 and/or no mention of 'exist' in URL -If you want to have a URL without port 8080 and the 'exist' part, so 'http://example.com/edoc/view.html' rather than 'http://example.com:8080/exist/apps/edoc', you need to adjust eXist's configuration. Depending on the way you deployed eXist, the port configuration can be found e.g. in the Jetty config files (e.g. `tools/jetty/etc/jetty-http.xml`). In eXist's main `controller-config.xml` change - - - -to - - - - -and in `exist-webapp-context.xml`, change - - /exist - -to - - / - -If you cannot access the collection or any of the builtin apps, e.g. Dashboard or monex, the “portal” might be blocking Jetty’s `/`-context. Try editing `tools/jetty/webapps/portal/WEB-INF/jetty-web.xml` and change the context to something different than `/` or `/exist`, e.g. `/portal`. -Most likely, Dashboard etc. will not be immediately accessible after the splash screen (which, on a production server, should not be a problem) but need to be accessed manually under `$server/apps/dashboard/index.html`. -(see https://sourceforge.net/p/exist/mailman/message/35823429/) - -Another way of doing this – and maybe a better one if this is available to you – is to use a reverse proxy to point to `exist/apps/edoc`. Depending on your setup, you may lose access to eXide or monex. To solve this, add the following to your `controller.xql` before any redirect that checks for `html`: - - - - - - - -and alike for monex. - -### data collection other than `data` -No problems are expected here as the scripts should be able to figure out the correct paths. As with all the other cases, please report any issues you may find. \ No newline at end of file diff --git a/doc/CSS-files-and-classes.md b/doc/CSS-files-and-classes.md deleted file mode 100644 index 0fb27ec1..00000000 --- a/doc/CSS-files-and-classes.md +++ /dev/null @@ -1,48 +0,0 @@ -## global CSS files - -All these files define global CSS rules. While it is possible to change them -directly, the preferred way to go is via -[[project specific files|project-specifics]] as these global files may be -replaced during an update or upgrade. - -|file|rules| -|--|--| -|resources/css/wdb.css|basic layout of any page – this one is loaded first by all pages in the templating system| -|resources/css/function.css| basic layout for function pages (small aside left, wide main right)| -|[[resources/css/view.css\|css-files-and-classes#viewcss]]| main layout file for _header_, _nav_, _main_ and _aside_ in of view.html| -|resources/css/search.css|additional layout for search page and results| -|[[resources/css/start.css\|css-files-and-classes#startcss]]| additional layout for `start.html`| -|[[resources/css/footnotes.css\|css-files-and-classes#footnotescss]]| additional layout for footnotes| - -## overview of classes -### view.css -|class / rule / id|intended for| -|--|--| -|header|the horizontal header at the top| -|main|main text area to the left| -|nav|(global) navigation| -|#wdbRight|the right hand side| -|#fac|container for facsimile (on the right)| -|#facsimile|iframe to load facsimiles| -|#wdbShowHide|central vertical bar to adjust size| -|#wdbContent|container for text in _main_| -|footer|the footer below a text (container)| -|span.dispOpts|options in the header (usually to the right)| -|#marginalia_container|container for marginalia| - -### footnotes.css -|class / rule / id|intended for| -|--|--| -|div.footnotes|container for all footnotes| -|#kritApp, #FußnotenApparat, #critApp, #apparatus|one group of notes| -|hr.fnRule|footnote rule (above)| -|a.fn_number|footnotes's identifier in the main text| -|.fn_number_app|footnotes's identifier within the footnote| -|span.footnoteText|footnote's text (usually after the identifier)| - - -### start.css -|class / rule / id|intended for| -|--|--| -|#toc_title|title for the table of contents| -|div.startImage|an image to be displayed on the right| \ No newline at end of file diff --git a/doc/Global-Configuration.md b/doc/Global-Configuration.md deleted file mode 100644 index d76b4aae..00000000 --- a/doc/Global-Configuration.md +++ /dev/null @@ -1,35 +0,0 @@ -# Global Configuration - -All global configuration options, i.e. those that affect how the app works, are set in `$approot/config.xml`. -If you use the [[default setup|basic-collection-structure#default-structure]], `$approot := /db/apps/edoc`. - -## Settings in `config.xml` -### meta -- `name` – a long title for this instance of the app -- `short` – a short title, e.g. to be used in `html:title` - -### role -- `type` – the [[role|server-roles]] of this instance -- `peer` – for a _workbench_, this points to the House of Lords, i.e. the _publication_ instance - -See the documentation of the [[server roles|server-roles]] for more detail. - -### params -- `param` – a key-value pair for global parameters that are available in all scripts and will be passed on to the model. - -Not really implemented yet but planned for version 2.0. - -### server -A full URL, reachable from the outside, to be used if the automatic resolution in `app.xql` does not work or needs to be overwritten. This needs to point to the collection containg `config.xml` (thus, the standard setting would be `http://yourexist.tld/exist/apps/edoc/`)– a setting here overwrites the automatic processing and will be globally available as `$wdb:edocBaseURL`, the server's name (or IP) as `$wdb:server`. -While all standard scripts should be able to figure this out correctly, certain setups may cause problems. - -Scripts invoked via RESTXQ will not be able to use automatic resolution – if you need the base URL from within a RESTXQ endpoint (e.g. for the IIIF image descriptor), you MUST set this option. - -### rest -A full URL which is the base for REST calls. This will be used by JavaScript functions, e.g. to load navigation or to insert/retrieve annotations. This must be set if the rest endpoint is not available under the usual location (i.e. `http://yourexist.tld/exist/restxq/edoc/` for the standard setup). This might be the case if you hid parts of the standard path by eXist's configuration or reverse proxying. - -NB: this needs to include the “edoc/” part - -## Projects -In order to create a project, you have to create a collection for it and make the most important settings in `wdbmeta.xml`. The initial settings can be done using `admin/admin.html` (New Project). -After that, you have to add at least one view and an entry for every file you want to access. \ No newline at end of file diff --git a/doc/Global-variables.md b/doc/Global-variables.md deleted file mode 100644 index 364552f1..00000000 --- a/doc/Global-variables.md +++ /dev/null @@ -1,35 +0,0 @@ -# Global variables -## $model - -In several instances, most prominently in `app.xqm`, a parameter called `$model` is passed to functions. -This is part of eXist's templating system and has been used in several locations to allow for uniform distribution of common parameters. - -`$model` always is a `map(*)`. The most important parameters MUST be the same in all instances. This means: - -| parameter | contents | -|--|--| -| `ed` | the ID of the Collection (= `@xml:id` of `meta:projectMD` or `mets:mets`) | -| `fileLoc` | full path to the current Resource | -| `id` | a file's ID (e.g. file to be displayed) | -| `infoFileLoc` | full path to `wdbmeta.xml` or `mets.xml` | -| `pathToEd` | the full DB-Path to the Collection (= `substring-before($infoFileLoc, '/wdbmeta.xml')`) | -| `projectFile` | path to Project’s `project.xqm`| -| `projectResources` | path to Project’s resource folder (= `substring-before($projectFile, 'project.xqm') || 'resources'`)| -| `title` | the title of the file or project | -| `view` (app.xqm only) | the `view` query parameter as pass in the call to `view.html` | -| `xslt` (app.xqm only) | full path to the XSLT to be used for transformation | -| `p` (function.xml only) | all values from `p` query parameter parsed into a `map(*)` | - - -## parameters in `wdb` namespace -The [[wdb namespace|list-of-namespaces]] contains several global parameters that can be accessed from every script that imports `app.xql`: - -|name|contents| -|--|--| -|`$wdb:edocBaseDB`| same as `$config:root` – the path to where the application is installed within `/db/`.| -|`$wdb:configFile`| the (parsed) config file (`{$wdb:edocBaseDB}/config.xml`).| -|`wdb:data`| the path to the data collection. It is assumed that this is the top collection with a `wdbmeta.xml` file.| -|`wdb:server`| the server's address including protocol and port – if automatic resolution does not work, set it manually in [[config.xml\|global-configuration]].| -|`$wdb:edocBaseURL`| the full URL to the app's root or the current subcollection.| -|`$wdb:role`| the [[role\|server-roles]] of this instance.| -|`$wdb:peer`| this instance's peer, if it is a workbench.| diff --git a/doc/Home.md b/doc/Home.md deleted file mode 100644 index c668592f..00000000 --- a/doc/Home.md +++ /dev/null @@ -1,15 +0,0 @@ -Welcome to the wdbplus wiki! - -To get started, please refer to the information in `project.md`. - -Some basic concepts etc. are to be documented here. Until there is a more definite documentation included within the app itself, this is the place for doc to go. It may also serve as a stable target for documentation of older releases. - -Your point of entry should be [[global-configuration]] which introduces you to the most important settings and caveats. - -If you want to know more about the structure of collections within the app and what you can change, please have a look at [[Basic Collection Structure|basic-collection-structure]]. This page also contains information about settings to change when you want to use a different setup, e.g. place the app outside of `/db/apps`. - -An overview of how projects can be customized and the app's configuration options, see [[project-specifics]] as well as [[wdbmeta.xml]] for project metadata. - -Functions you can use are listed in [[the list of JavaScript functions|js-functions]] and [[the list of XQuery functions|xq-functions]]. - -To learn about what the most important files in this app do, consult [[the list of main HTML files|main-html-files]] and [[the list of other main files|main-files]]. \ No newline at end of file diff --git a/doc/Include-an-image-viewer-via-projectSpecifics.md b/doc/Include-an-image-viewer-via-projectSpecifics.md deleted file mode 100644 index 39da0500..00000000 --- a/doc/Include-an-image-viewer-via-projectSpecifics.md +++ /dev/null @@ -1,68 +0,0 @@ -As an example how to use projectSpecifics and as a how-to for embedding a viewer, we will have a look at how to include the OpenSeaDragon viewer in your project or instance. - -1. Images are usually displayed to the right. So we need to include the viewer in the right part of `view.html`, which is the element `aside` (on the basic page layout cf. [[main-html-files]]). To include the necessary files, we will create a footer here. A globally defined footer will live in `edoc/resource/rightFooter.html` while a project specific footer will be located in `edoc/data/yourProject/resource/projectRightFooter.html` or defined by a function `wdbPF:getProjectRightFooter`. -1. Create a JS file `osdviewer.js` for all functions necessary for the viewer in `edoc/resource` or ``edoc/data/yourProject/resource`: - - $.holdReady(true); - var viewer = OpenSeadragon({ - preserveViewport: true, - visibilityRatio: 1, - minZoomLevel: 1, - defaultZoomLevel: 1, - id: "fac", - sequenceMode: true, - tileSources: [] - }); - - id = $("meta[name='id']").attr("content"); - rest = $("meta[name='rest']").attr("content"); - $.get(rest + "resource/iiif/" + id + "/images", function(data){viewer.open(data);}); - - viewer.addHandler('page', function(source, page, data){ - $('#pag' + (source.page + 1))[0].scrollIntoView(); - }); - viewer.addHandler('open', function() { $.holdReady(false); }); - -1. In this example, we create the HTML file with only one line: - - - - Adjust the path in `@src` to point to where you stored the JS in the step before. -1. In a project’s `project.xqm` (or the global `project.xqm` for those projects without their own), load the main OpenSeadragon JS. Change `wdbPF:getProjectFiles` so it looks similar to this (of course you should keep `link` or `script` elements you already added): - - declare function wdbPF:getProjectFiles ( $model as map(*) ) as node()* { - ( - , -