From de647a65f19c5d6c9c9b88e861979d8ed837a437 Mon Sep 17 00:00:00 2001 From: krHERO Date: Thu, 14 Nov 2024 13:42:51 +0100 Subject: [PATCH 1/7] move release workflow from wiki to docs we want to move all information regarding (technical) documentation to edirom-online/docs from the wiki. description of release workflow is a part of this. Refs #https://github.com/Edirom/Edirom-Online/issues/415 --- docs/release-workflow.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/release-workflow.md diff --git a/docs/release-workflow.md b/docs/release-workflow.md new file mode 100644 index 000000000..3de762901 --- /dev/null +++ b/docs/release-workflow.md @@ -0,0 +1,23 @@ +# Edirom Online – Release Workflow + +- `git checkout develop` +- have a look into release-milestone and manage last issues and PRs +- `git checkout -b rel/1.0.0-beta.[X] develop` +- bump version in build.xml +- commit version release branch +- build `.xar` and test it. +- `git checkout main` +- `git merge --no-ff rel/1.0.0-beta.[X]` (release branch into main) +- propably resolve merge conflicts and `git continue merge`(?) +- `git tag` returns a list of all tags +- `git tag -a v1.0.0-beta.[X] -m "v1.0.0-beta.[X]"` +- probably `git tag` for review +- `git push --follow-tags` +- on github.com: Go to tag and klick `Release from Tag` +- auto-generate the release description +- upload the tested `Edirom-Online-1.0.0-beta.[X].xar` (asset) +- publish the release on Github +- `git checkout develop` +- `git merge --no-ff rel/1.0.0-beta.[X]` (release branch into develop) + +first version of this file was written by @riedde, 22.12.20222 (wiki) From b6012ecd3af1dadb244d21cf97f289fcc5d7e2c1 Mon Sep 17 00:00:00 2001 From: krHERO Date: Thu, 14 Nov 2024 15:42:58 +0100 Subject: [PATCH 2/7] move customize content from wiki to docs we want to move all information regarding (technical) documentation to edirom-online/docs from the wiki. description of customization is a part of this. The content was taken from several places in the wiki and integrated to a newly introduced structure of this file. Refs https://github.com/Edirom/Edirom-Online/issues/415 --- docs/customize.md | 160 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 docs/customize.md diff --git a/docs/customize.md b/docs/customize.md new file mode 100644 index 000000000..2721835d9 --- /dev/null +++ b/docs/customize.md @@ -0,0 +1,160 @@ +# Customize Edirom Online + +## Annotations +change the **layout** for annotations (3 are predefined), using predefined preferences +* `` + +## CSS +Add a **custom CSS file**, using predefined preferences +* `` + +## Image server ### +**switch the image server** from digilib to openseadragon (IIIF), using predefined preferences +* `` + +## Topbar +change the **logo** of the edition +* edit [`app/view/desktop/TopBar.js`](https://github.com/Edirom/Edirom-Online/blob/f8abab67bd86cb055859be8fdb9965602477e854/app/view/desktop/TopBar.js#L72) +* then edit [`Edirom-Online/packages/eoTheme/sass/var/button/Button.scss`](https://github.com/Edirom/Edirom-Online/blob/f8abab67bd86cb055859be8fdb9965602477e854/packages/eoTheme/sass/var/button/Button.scss#L215) + +de/activate **search** +* un/comment [`Edirom-Online/app/view/desktop/TopBar.js`](https://github.com/Edirom/Edirom-Online/blob/f8abab67bd86cb055859be8fdb9965602477e854/app/view/desktop/TopBar.js#L84) + +de/activate **work switch** +* un/comment [`Edirom-Online/app/view/desktop/TopBar.js`](https://github.com/Edirom/Edirom-Online/blob/f8abab67bd86cb055859be8fdb9965602477e854/app/view/desktop/TopBar.js#L82) + +## Welcome window +**define** a welcome window +* `` + +# Customize content + +## SVG overlays +Edirom Online offers the possibility to add SVG overlays to source images that can be switched on and off dynamically. Defining such an overlay requires two steps. + +**Add SVGs to facsimile** + +You have to add the SVG to be displayed as overlay of a page to the respective mei:surface in the mei:facsimile tree, e.g.: + +``` + + + + + + + + ... + + + +``` + +Please be aware, that Edirom does not provide a tool for generating theses SVGs, you have to use any appropriate image editing software, simple SVGs can easily be created in the XML directly, though. There are several issues that You should take care when creating the SVG. + +1. The SVG element has to have an @xml:id in order to associate it with the layer definition. Otherwise it will not be displayed when the layer is being switched on in the Source-View. +2. The SVG should have the exact same proportions as the image file of the page on which it is to be displayed. The easiest way is to give it the exact same pixel dimensions, both in the @widht and @height attributes, and in the @viewbox attribute. +A feature currently under development is adding interactivity to SVG shapes. When ready this will allow to add the @onclick attribute to a shape that could trigger, e.g. loading some Ediron Online content in a new window (see above example). + +**Define overlay** + +In order to have the overlay displayed as option in a sources's View-Menu resp. Layers-Menu a mei:annot has to be defined in the mei:notesStmt, e.g. + +``` + + + Title to be shown in Menu + + +``` + +The mei:annot has to be conform to the following issues: +1. @type="overlay" +2. @xml:id has to be present +3. @plist has to contain IDREFs to all SVG elements in the source that shall be associated with the corresponding entry in the View-Menu, i.e. the SVG elements of all facsimile surfaces that shall be displayed when the layer is set visible. Of course the overlay will only display the SVG associated with the source-page currently displayed. + +## Windows + +**dimensions of content windows**: when opened e.g. from the Navigator, window height is set to the max. desktop height, width is set to x% of the desktop's width. You can set the initial width of every content window by propagating it together with the calling link in the navigator in [edition].xml: +* ` + + Score + +` + + +# Links + +## Links to XML in the eXist-database + +These xmldb-uris are generally used by Edirom Online to open contents. + +**Link to source** +* opening default view: `xmldb:exist:///ABSOLUTE-PATH-TO-RESOURCE`, e.g. `xmldb:exist:///db/contents/edition-12345678/sources/source1.xml` + +**Open a specified location in the source** +* `xmldb:exist:///ABSOLUTE-PATH-TO-RESOURCE#XML-ID` + * e.g., a page `xmldb:exist:///db/contents/edition-12345678/sources/source1.xml#edirom_surface_87c87e5d-37bc-463d-9f13-6d2940472db2` + * e.g., a measure `xmldb:exist:///db/apps/contents/musicSources/freidi-musicSource_A.xml#A_mov0_measure11` + * to specify multiple resources, concatenate their xmldb URIs with `;`: `[xmldb-URI];[xmldb-URI]` + +## Links from outside Edirom Online + +**Link to Edirom Online** +* Depending on the domain of your deployment, the server setup etc. in a standard local server environment this might be: `http://localhost:8080/exist/apps/EdiromOnline/` +* Link to Edirom Online setting the active edition `http://localhost:8080/exist/apps/EdiromOnline?edition=[EDITION-ID]` +* Link to Edirom Online setting the active work `http://localhost:8080/exist/apps/EdiromOnline?work=[WORK-ID]` This will automatically also set the `activeEdition`. + +**Link to Edirom Online opening a specified window/object** +* In addition to the above 'link to Edirom Online' use the `uri` parameter to supply a xmldb-uri ([see above](#Links-to-xml-in-the-exist-database)) to the database content that should be opened in Edirom Online, e.g.: `http://localhost:8080/exist/apps/EdiromOnline/?uri=xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml` +* Edirom Online will open the objects in their respective default view and window size. + +**Link to Edirom Online opening multiple specified windows/objects** +* As the above plus append additional resource-links separated by `;`, e.g.: `http://localhost:8080/exist/apps/EdiromOnline/?uri=xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml;xmldb:exist:///db/apps/contents/librettoSources/freidi-librettoSource_KA-tx4.xml` + +## JS + +The function-handling links in Edirom Online are defined by the [app/controller/LinkController.js](https://github.com/Edirom/Edirom-Online/blob/develop/app/controller/LinkController.js) as follows: +```js +loadLink: function(uri, cfg){ ... } +``` + +The two parameters given are: +* **uri** any uri may be entered; nevertheless there are mechanisms for relative or absolute links and some special cases for certain 'protocols' such as 'edirom:' or 'xmldb:exist' +* **cfg** is an JS object containing various options for defining things such as opening a link in a new Edirom Online window or defining width of the openend window. + +***Examples*** + +* open **object window** in default view with default parameters +```js +loadLink('xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml',{}); +``` +* open **target element** in its default view (e.g. open a specific measure of a music source in measureBasedView) +```js +loadLink('xmldb:exist:///db/apps/contents/musicSources/freidi-musicSource_A.xml#A_mov0_measure11',{}); +``` +* open object window in default view with **defined window width** +```js +loadLink('xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml',{width:'600px'}); +``` +* **Update a window** that’s already displaying a resource + * If the resource is not open in any window a new window will be opened + ```js + window.parent.loadLink('xmldb:exist:///db/apps/contents/musicSources/freidi-musicSource_A.xml#A_mov0_measure11', {useExisting:true}); + ``` + * If the resource is not open in any window, ignore the link + ```js + window.parent.loadLink('xmldb:exist:///db/apps/contents/musicSources/freidi-musicSource_A.xml#A_mov0_measure11', {onlyExisting:true}); + ``` +* Open **multiple resources** +```js +window.parent.loadLink('xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml;xmldb:exist:///db/apps/contents/musicSources/freidi-musicSource_A.xml#A_mov0_measure11'); +``` + * Additionally sort the resources after they have been opened (at the moment this option only supports the `sortGrid` option) + ```js + window.parent.loadLink('xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml', {sort:’sortGrid'}); + ``` + * If at the same instance windows that are already opened (array of window-objects) should be included in the sort. This is used with the "open all" Button in annotation windows to include the annotation window in the sort + ```js + window.parent.loadLink('xmldb:exist:///db/apps/contents/audioSources/freidi-recording_Janowski1994.xml', {sort:’sortGrid’,sortIncludes:[win1,win2]}); + ``` From c1be9834372480343de21783232901cefd206142 Mon Sep 17 00:00:00 2001 From: krHERO Date: Thu, 14 Nov 2024 15:49:29 +0100 Subject: [PATCH 3/7] add toc since the file has several topics and subtopics this commit adds a table of content. Refs https://github.com/Edirom/Edirom-Online/issues/415 --- docs/customize.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/customize.md b/docs/customize.md index 2721835d9..a6df7a867 100644 --- a/docs/customize.md +++ b/docs/customize.md @@ -1,3 +1,20 @@ +# Customize Edirom Online and content + +- [Customize Edirom Online](#customize-edirom-online) + * [Annotations](#annotations) + * [CSS](#css) + * [Image server](#image-server) + * [Topbar](#topbar) + * [Welcome window](#welcome-window) +- [Customize content](#customize-content) + * [SVG overlays](#svg-overlays) + * [Windows](#windows) +- [Links](#links) + * [Links to XML in the eXist-database](#links-to-xml-in-the-exist-database) + * [Links from outside Edirom Online](#links-from-outside-edirom-online) + * [JS](#js) + + # Customize Edirom Online ## Annotations From d42b48ce685f83e36bdbf90f75b92999f796e16f Mon Sep 17 00:00:00 2001 From: krHERO Date: Thu, 14 Nov 2024 15:52:11 +0100 Subject: [PATCH 4/7] Update release-workflow.md minor typo Refs https://github.com/Edirom/Edirom-Online/issues/415 --- docs/release-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-workflow.md b/docs/release-workflow.md index 3de762901..9c6576f4c 100644 --- a/docs/release-workflow.md +++ b/docs/release-workflow.md @@ -20,4 +20,4 @@ - `git checkout develop` - `git merge --no-ff rel/1.0.0-beta.[X]` (release branch into develop) -first version of this file was written by @riedde, 22.12.20222 (wiki) +first version of this file was written by @riedde, 22.12.2022 (wiki) From e6fc574d369130b878aeed5b7c364f124e4c8514 Mon Sep 17 00:00:00 2001 From: krHERO Date: Thu, 14 Nov 2024 17:43:16 +0100 Subject: [PATCH 5/7] create setup.md this commit adds a detailed setup description for Edirom-Online and a data package. It is more detailed than in the readme.md to make every step as clear as possible, since the readme.md instructions are fine for advanced developers that need only a short and quick description. thanks to @feuerbart for capturing this during the edirom-summer-school 2024. i corrected only some minor typos and changed only a little bit regarding the structure. Refs https://github.com/Edirom/Edirom-Online/issues/415 --- docs/setup.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/setup.md diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 000000000..386f40565 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,87 @@ +# Setup Edirom Online on a local machine + + + +This guide will explain step by step how to **build Edirom Online**, the **EditionExample data package**, setup an **exist-db** on your local machine and upload both packages to it. We tested it on MacOS, but it should work on every OS. +You need to install *Docker* and either *Apache Ant* or *oXygen XML-Editor*. Its recommended to install *git* but you can also download the required files from the git-repos without git. + +**Prerequisites** + +- open terminal-window (Windows: Powershell) and navigate to the path where you want the Edirom Online-files to be saved: e.g. `cd /home//repos` +- create a folder on your disc for the files: `mkdir edirom` +- go in that folder: `cd edirom` + +## Build Edirom Online + +If you only want to “use” Edirom Online, downloading a prebuild package is all you need to do. Go to the [releases](https://github.com/Edirom/Edirom-Online/releases) of the github-repo of edirom-online, chose your version and download the xar-package. +If you want to customize it, you need to build it and create a xar-package by yourself by following the description below. + +- fork the [develop-branch](https://github.com/Edirom/Edirom-Online) of the Edirom Online Github repository +- **clone** your fork to your disk + - `git clone git@github.com:/Edirom-Online.git` (change ``to your github-username) + - this will checkout the latest version of Edirom Online, if you want an earlier version, you can manually checkout that commit +- navigate to the repository: `cd Edirom-Online` +- to **build** the Edirom Online we need *[Sencha Cmd](https://www.sencha.com/)*, but we can use the sencha-cmd-docker-image by @bwbohl instead of installing sencha on our own. + - download and run the sencha-cmd-image: + ``` + docker run --rm -it -v `pwd`:/app --name ediBuild ghcr.io/bwbohl/sencha-cmd:latest) + ``` + - this will build a docker-container giving us the opportunity to execute commands inside the container, but we still have access to the current directory, the terminal-prefix will change to something like this: `root@d5f2f1591708:/app#` + - execute the build-script: `sh build.sh` + - some warnings will appear, but you can savely ignore them + - it will take a minute or so to build and return the following + ``` + BUILD SUCCESSFUL + Total time: 17 seconds + root@d5f2f1591708:/app# + ``` + - the Edirom Online-package is built, we can leave docker-container: `exit` + - the directory `build-xar/` was created inside the Edirom-Online repository and contains the built xar-file of Edirom Online: `Edirom-Online-1.0.0-beta.6-20240926-1521.xar` (version and date-strings will vary) +- navigate back to the edirom-base-directory: `cd ..` + +## Build data package + +The [EditionExample](https://github.com/Edirom/EditionExample) is a good way to test if your Edirom Online works correctly and a good starting point for your own edition. +- fork the EditionExample repository: https://github.com/Edirom/EditionExample +- clone the forked repository to your disk: `git clone git@github.com:/EditionExample.git` (change ``to your github-username) +- navigate to the directory: `cd EditionExample` +- open `build.xml` with *oXygen* and click the run-button, oXygen will do the rest automatically + - if you have *Apache Ant* installed, you also can execute it manually: `ant` +- the directory `dist/` will be created and contains the built data package: `EditionExample-0.1.xar` +- leave the EditionExample directory: `cd ..` + +## Create an exist-db on your local machine + +Well done, we created the build of Edirom-Online and the one for the data package (EditionExample). To see the edition on your local machine, the last step is to load both xar-packages into an [exist-db](https://exist-db.org/exist/apps/homepage/index.html). +Also at this step we can use a docker image, instead of downloading exist on our own. +- run the docker image provided by @peterstadler: `docker run -it -p 8080:8080 --name existdb -e EXIST_ENV=development -e EXIST_CONTEXT_PATH=/exist stadlerpeter/existdb:6` + - if you only want to run the container once, you can add the flag `--rm` then it will be deleted after you stop it +- exist-db will start in a docker container, it is ready if the following is shown: + ``` + 26 Sep 2024 15:49:45,369 [main] INFO (JettyStart.java [run]:288) - ----------------------------------------------------- + 26 Sep 2024 15:49:45,369 [main] INFO (JettyStart.java [run]:289) - Server has started, listening on: + 26 Sep 2024 15:49:45,370 [main] INFO (JettyStart.java [run]:291) - http://172.17.0.2:8080/ + 26 Sep 2024 15:49:45,370 [main] INFO (JettyStart.java [run]:291) - https://172.17.0.2:8443/ + 26 Sep 2024 15:49:45,370 [main] INFO (JettyStart.java [run]:294) - Configured contexts: + 26 Sep 2024 15:49:45,371 [main] INFO (JettyStart.java [run]:300) - /exist (eXist XML Database) + 26 Sep 2024 15:49:45,374 [main] INFO (JettyStart.java [run]:316) - /exist/iprange (IPrange filter) + 26 Sep 2024 15:49:45,375 [main] INFO (JettyStart.java [run]:324) - ----------------------------------------------------- + ``` +- once the exist-db is ready, you can open its dashboard in your browser: [`http://localhost:8080/exist/apps/dashboard/index.html`](http://localhost:8080/exist/apps/dashboard/index.html) +- login to the exist-db via the "Login" button in the top right corner: + - user: admin + - pass: will be random-generated, but printed in the exist-db container output above, it looks like that: + ``` + no admin password provided + setting password to Thh3Mj3iUYG2OYpakbslXiTs + ``` + - you might also want to save that password, because it wont be shown elsewhere +- go to "Package Manager" in the menu on the left and upload the two previously generated xar-packages + - `Edirom-Online-1.0.0-beta.6-20240927-0804.xar` + - `EditionExample-0.1.xar` +- once the upload is finished, the edirom will be available here: [`http://localhost:8080/exist/apps/Edirom-Online/index.html`](http://localhost:8080/exist/apps/Edirom-Online/index.html) (if not, a reload of the browser window may help) +- you can stop the docker container with `^+C` (Mac) or `CTRL+C` (Windows and Linux) or force-stop it by closing the terminal +- once you stopped the exist-db docker container, you can start it with the following command: `docker start existdb` and after a short time the Edirom Online will be available again. `docker stop existdb` will stop it. + +--- +*first version of this file was written by @feuerbart, 26./27.9.2024 at the [Edirom-Summer-School](https://ess.uni-paderborn.de/) in discussion with @riedde and @krHERO* From a7f94762dea1def10248fef4a3e5d621cbe03cc5 Mon Sep 17 00:00:00 2001 From: krHERO Date: Fri, 15 Nov 2024 21:54:30 +0100 Subject: [PATCH 6/7] move old (deprecated) technical documentation from wiki to edirom-online/docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit to have this information captured once before it will be updated by future releases, it will be saved with this commit. The documentation was written 2015–2017. Refs https://github.com/Edirom/Edirom-Online/issues/415 --- .../old-deprecated-documentation-from-wiki.md | 335 ++++++++++++++++++ 1 file changed, 335 insertions(+) create mode 100644 docs/old-deprecated-documentation-from-wiki.md diff --git a/docs/old-deprecated-documentation-from-wiki.md b/docs/old-deprecated-documentation-from-wiki.md new file mode 100644 index 000000000..4b29831ec --- /dev/null +++ b/docs/old-deprecated-documentation-from-wiki.md @@ -0,0 +1,335 @@ +# Setup Edirom-Online + +**!!! PLEASE NOTE: The following instructions are taken from the wiki, where in former times of Edirom-Online the technical documentation was living. +This is changing during the v1.0.0 release. The content of the technical documentation is moving to edirom-online/docs and updated and enhanced. This current file is existing only temporarily at this place and will be removed in future releases. +But it is kept for now in concerns of older releases and to have it captured in the commit-history. Thanks to its commit history this file can be consulted anytime while using the v1.0.0 release package. +Just for information: Content below every first level topic was its own wiki-page. The latest updates to the technical documentation in the wiki were made in 2017, detailed dates below every first level topic.!!!** + +- [Getting Edirom-Online](#getting-edirom-online) + * [Edirom-Online as a service](#edirom-online-as-a-service) + + [Installing components](#installing-components) + + [Installing Edirom-Online](#installing-edirom-online) + - [Prerequisites](#prerequisites) + - [Download, configure, build and install Edirom-Online](#download--configure--build-and-install-edirom-online) + * [Configure](#configure) + * [Build](#build) + * [Install](#install) +- [Build Process](#build-process) +- [Problems with the Edirom Online Wrapper](#problems-with-the-edirom-online-wrapper) +- [Installing components on OS X](#installing-components-on-os-x) + * [Preparing your system](#preparing-your-system) + * [Install and configure eXist-db](#install-and-configure-exist-db) + * [Install and configure the Jetty Application Server](#install-and-configure-the-jetty-application-server) + * [Install and configure Digilib](#install-and-configure-digilib) +- [Preparing your content for Edirom Online](#preparing-your-content-for-edirom-online) + * [Overview](#overview) + * [Exporting your edition's data](#exporting-your-edition-s-data) +- [Getting your content into Edirom Online](#getting-your-content-into-edirom-online) + * [Prerequisites](#prerequisites-1) + * [Importing your edition's data to eXist-db](#importing-your-edition-s-data-to-exist-db) + * [Importing your edition's image files to Digilib](#importing-your-edition-s-image-files-to-digilib) + + [Optional: Advanced image handling](#optional--advanced-image-handling) + +# Getting Edirom-Online +*(last modification of this section in the wiki 17.1.2017)* + +You have two different options. Installing Edirom-Online as a web service on your server/computer or using it as desktop application which will be provided for download in the future. + +## Edirom-Online as a service + +To run Edirom-Online as a service you have to install the following components: + +* Jetty Application Server (), in the newest version (tested with version 9.2.3) +* eXist-db (), in the newest version (tested with version 2.2) +* Digilib (), in the newest version (tested with version 2.2) +* Apache with mod_proxy () + +Install eXist-db and Digilib on different ports. We use Jetty as application server for Digilib, others should work, too. You will find step-by-step guides for different platforms in the following sections. + +### Installing components + +* Linux +* [Mac OS X](Installing-components-on-OS-X) +* Windows + +### Installing Edirom-Online + +#### Prerequisites + +Edirom Online depends heavily on the javascript framework [ExtJS](http://www.sencha.com/products/extjs/) by Sencha which is included in parts in our code base. We use ExtJS 4.2.1 in the GPL version. To configure and customize Edirom-Online you will need [Sencha Cmd](http://www.sencha.com/products/sencha-cmd/). Please download and install Version 4.0.4.84 from [this site](http://www.sencha.com/products/sencha-cmd/download/) at "Related Links". For further information see [Sencha Cmd documentation](http://docs.sencha.com/cmd/5.x/intro_to_cmd.html). + +We assume, that you have Secha Cmd installed in your home directory at ~/bin and that you have edited your PATH environmental variable as follows: + +* Edit or create _.profile_: `nano ~/.profile` on macOS Sierra `nano ~/.bash_profile` respectively + +* Insert the line: `export PATH=~/[YourUser]/bin/Sencha/Cmd/4.0.4.84:$PATH` + +#### Download, configure, build and install Edirom-Online + +* Optional: Fork Edirom-Online for your project and download or check out the code from there (see next step). + +* Download or check out [Edirom-Online](https://github.com/Edirom/Edirom-Online.git) to a local directory of your choice. + +* [Prepare your edition content for Edirom-Online using Edirom-Editor](Preparing-your-content-for-Edirom-Online). + +* [Copy your edition content (MEI, TEI and image files)](Getting-your-content-into-Edirom-Online) to the appropriate locations. + +##### Configure + +* Go to `[PathToYourEdirom-OnlineDirectory]/app/Application.js` and edit l. 61 and 62 to point to your edition's content in eXist-db: + +```XML +activeEdition: 'xmldb:exist:///db/contents/[PathToYourEdition.xml]', +activeWork: 'edirom_work_[WorkID]', +``` +___ + +Following our [instructions](Getting-your-content-into-Edirom-Online) this should be equal to: + +```XML +activeEdition: 'xmldb:exist:///db/contents/edition-MyEdition.xml', +activeWork: 'edirom_work_[WorkID]', +``` +___ + +* Go to `[PathToYourEdirom-OnlineDirectory]/app/view/window/image/ImageViewer.js` and change l. 45 to: + +```JavaScript +imgPrefix: 'http://[IP_or_DomainOfJettyDigilib]:[Port]/digilib/Scaler/' +``` + +* Go to `[PathToYourEdirom-OnlineDirectory]/add/data/prefs/edirom-prefs.xml` and change l. 28 to: + +```XML + +``` + + +##### Build + +* Go to `[PathToYourEdirom-OnlineDirectory]/` and build Edirom-Online by typing: `./build.sh` + +* After building you will find your Edirom-Online application package in `[PathToYourEdirom-OnlineDirectory]/build-xar/Edirom-Online-0.1-[DateAndTimeOfBuild].xar` + +##### Install + +* Open your eXist-db dashboard at _http://[IP_or_DomainOfeXist-db]:8080_, authenticate as admin and open the _Package Manager_. + +* Install your Edirom-Online by clicking on the blue "+"-button in the upper left corner of _Package Manager_ and upload your Edirom-Online xar file. + +* When the upload has finished close _Package Manager_. You will find a new application icon _"Edirom Online"_ in your eXist-db dashboard. By clicking on it your Edirom-Online should start in a new browser window or tab. + +# Build Process +*(last modification of this section in the wiki 31.6.2016)* +* **How can I debug Edirom Online?** Prior to building the app go to `[PathToYourEdirom-OnlineSourceDirectory]/index.html` and change l. 38 to ``. Then build and upload the app and use Firefox/Firebug to debug your code. + +# Problems with the Edirom Online Wrapper +*(last modification of this section in the wiki 19.2.2015)* +_Problem_: **On a Windows computer the Edirom Online starts, but the edition is not shown** + +_Description_: On Windows machines sometimes the default program for Javascript files is changed. Javascript is used to start the internal server. In most cases, when this error occures, the file `startServer.js` is opened in a text editor or another program. In this case the internal server for Edirom Online is not started correctly. + +_Solution_: The default program for Javascript files has to be reset in the registry. 1. Type `regedit` in the command prompt to access the registry. 2. Change the default value of the key `HKEY_CLASSES_ROOT\.js` to the string `JSFile` + +# Installing components on OS X +*(last modification of this section in the wiki 17.1.2017)* + +This step-by-step guide reflects the installation of the needed components on a Mac running **OS X 10.9.5** Mavericks. + +## Preparing your system + +Perform all needed system updates and install Java. Until OS X 10.9 Apple provided its own Java (1.6) implementation as an optional installation aside the newer Java releases by Oracle (1.7/1.8). From OS X 10.10 onwards you are guided to the Oracle Java download pages (https://www.java.com/de/download/). Nevertheless which version of OS X you are using, please make sure to have the most current release of Java installed. + +## Install and configure eXist-db + +Download the installer. To install eXist-db respectively Edirom-Online on a (probably "headless") Server we take the JAR-file of the current stable release of eXist-db: http://sourceforge.net/projects/exist/files/Stable/. + +Create the directory `/Library/eXist` and install eXist-db into it by following the instructions for headless installation in the eXist-db [Documentation](http://exist-db.org/exist/apps/doc/documentation.xml) section [Advanced Installation Methods](http://exist-db.org/exist/apps/doc/advanced-installation.xml#headless). To automatically start eXist-db at system startup it is important to run the command +`sudo /Library/eXist/tools/wrapper/bin/exist.sh install` after installation. This will create and load a LaunchDaemon named `org.eXist-db.wrapper.eXist-db.plist` in `/Library/LaunchDaemons`. + +Create a daemon user _eXist_ which will be responsible for running eXist-db. You can do this manually in the _User_ section of _System Preferences_. A more convenient possibility is to use a script provided [here](http://serverfault.com/a/532860) (see instructions there). This will create an appropriate OS X daemon user which won't appear in the list of users shown in the GUI. + +You can now tell your system to execute eXist-db as user _eXist_: + +* Unload the LaunchDaemon: `sudo launchctl unload -w /Library/LaunchDaemons/org.eXist-db.wrapper.eXist-db.plist` + +* Change permissions on /Library/eXist: `sudo chown -R _exist:_exist /Library/eXist` + +* Edit the LaunchDaemon (`sudo nano /Library/LaunchDaemons/org.eXist-db.wrapper.eXist-db.plist`) and insert the key _UserName_ and the string "_exist". The complete plist file is shown here: + + + + + + Label + org.eXist-db.wrapper.eXist-db + ProgramArguments + + /Library/eXist/tools/wrapper/bin/./exist.sh + launchdinternal + + UserName + _exist + OnDemand + + RunAtLoad + + + + +* Make sure that _root_ is still the owner of the plist file: `sudo chown root:wheel /Library/LaunchDaemons/org.eXist-db.wrapper.eXist-db.plist`. Otherwise the LaunchDaemon won't load on system boot. + +* Load the LaunchDaemon: `sudo launchctl load -w /Library/LaunchDaemons/org.eXist-db.wrapper.eXist-db.plist`. + +You can test your configuration by opening _http://[IP_or_DomainOfeXist-db]:8080_ in your browser. You should now see the eXist-db dashboard. + +Optional: You can change the port on which eXist-db respectively the underlying Jetty Application Server ist listening. Open `/Library/eXist/tools/jetty/etc/jetty.xml` and change the value of _jetty.port_ to the desired value in line 38: + + + +See also the section [Troubleshooting – Port Conflicts](http://exist-db.org/exist/apps/doc/troubleshooting.xml#port-conflicts) in the eXist-db Documentation. + +After changing the port stop and restart eXist-db by unloading and loading the LaunchDaemon. + + +## Install and configure the Jetty Application Server + +Download your prefered package for the latest stable release from: http://download.eclipse.org/jetty/. + +Create the directory `/Library/Jetty` and copy the extracted content of the downloaded package to this directory. + +Create the user _jetty_ to run this Jetty instance the same way as in the eXist-db section above. + +Change ownership of the directory `/Library/Jetty` to this new user: `sudo chown -R _jetty:_jetty /Library/Jetty`. + +To be able to start the Jetty server on system boot, create a new LaunchDaemon plist file: `sudo nano /Library/LaunchDaemons/org.eclipse.jetty.plist`. See the complete plist file here. + + + + + + Label + org.eclipse.jetty + WorkingDirectory + /Library/jetty + ProgramArguments + + /user/bin/java + -jar + start.jar + + UserName + _jetty + RunAtLoad + + KeepAlive + + + + +Save the plist file and verify that it is owned by _root_: `sudo chown root:wheel /Library/LaunchDaemons/org.eclipse.jetty.plist` + +Because this Jetty server instance will listen to the same port as eXist's build in Jetty Server, we have to change the port here: `sudo nano /Library/jetty/start.d/http.ini`and change the value of _jetty.port_ to _8081_. For more information on this please see [Changing the Jetty Port](http://www.eclipse.org/jetty/documentation/current/quickstart-running-jetty.html#quickstart-changing-jetty-port) in the [Jetty Documentation](http://www.eclipse.org/jetty/documentation/current/). + +Now you can load the LauchDaemon to start this Jetty instance: `sudo launchctl load -w /Library/LaunchDaemons/org.eclipse.jetty.plist`. You shold now be able to access the server in your browser on the adress: _http://[localhost_or_IP]:8081_. + +## Install and configure Digilib + +Download the latest stable release from: http://sourceforge.net/projects/digilib/files/. + +We will install Digilib as a web application provided by the previously installed Jetty Application Server. For further information on installing and configuring Digilib please see the [Digilib Documentation](http://digilib.sourceforge.net/index.html) pages. + +* Stop Jetty: `sudo launchctl unload -w /Library/LaunchDaemons/org.eclipse.jetty.plist` + +* Create a directory for the Digilib web application: `sudo mkdir /Library/Jetty/webapps/digilib` + +* Copy the downloaded Digilib war file to this directory and extract it: `jar -xf digilib-webapp-2.2.2-srv2.war` + +* Delete the war file: `sudo rm /Library/Jetty/webapps/digilib/digilib-webapp-2.2.2-srv2.war` + +* Create a directory _contents_ with three subdirectories named _images-100_, _images-50_, _images-25_: + + * `sudo mkdir /Library/Jetty/webapps/digilib/contents` + + * `sudo mkdir /Library/Jetty/webapps/digilib/contents/images-100` + + * `sudo mkdir /Library/Jetty/webapps/digilib/contents/images-50` + + * `sudo mkdir /Library/Jetty/webapps/digilib/contents/images-25` + +* Duplicate the configuration file _digilib-config.xml.template_ to _digilib-config.xml_: `sudo cp /Library/Jetty/webapps/digilib/WEB-INF/digilib-config.xml.template /Library/Jetty/webapps/digilib/WEB-INF/digilib-config.xml` + +* Edit _digilib-config.xml_ and define the parameter _basedir-list_: + * `sudo nano /Library/Jetty/webapps/digilib/WEB-INF/digilib-config.xml` + + * change the paramaeter `basedir-list` (line 18) to: + + + +* Copy an example image file to the directory _images-100_. + +* Start Jetty: `sudo launchctl load -w /Library/LaunchDaemons/org.eclipse.jetty.plist` + +You can now check your Digilib installation by opening _http://[IP_or_DomainOfJettyDigilib]:8081/digilib/_. You should see a list with files and direcories. You should also be able to open _http://[IP_or_DomainOfJettyDigilib]:8081/digilib/digilib.html_, where you will see Digilib's image viewer interface and your example image file. As a third test it should be possible to directly access your image file in the browser at _http://[IP_or_DomainOfJettyDigilib]:8081/digilib/Scaler/[your_image_file]?mo=file_. + +You are now ready to install Edirom-Online proceeding the instructions at [Installing Edirom-Online](Getting-Edirom-Online#installing-edirom-online). + +# Preparing your content for Edirom Online +*(last modification of this section in the wiki 18.7.2017)* + +## Overview +You can prepare content for _Edirom Online_ using the _Edirom Editor_. The released versions of _Edirom Editor_ can be tretrieved from https://github.com/Edirom/Edirom-Editor/releases, please also see https://github.com/Edirom/Edirom-Editor/ for system requirements. Its online help can be found at http://www.edirom.de/EdiromEditor/help/. + +Alternatively you can start out from https://github.com/Edirom/EditionExample (currently under development) to give you a first insight into the data model and contents of Edirom Online. + +## Exporting your edition's data + +Having prepared your content in Edirom-Editor, you have to export your data following these steps: +* Mark one or more works you want to export for Edirom-Online in the library view (main window) and click on the export button in the lower left section (button with the export arrow). +* In the export dialogue choose _Edirom Online_ as the target application, fill in the (optional) requested information and click _Export_. You will then be asked to specify a location on your computer where Edirom-Editor will save the exported data. + +To be able to proceed with ["Getting your content into Edirom-Online"](Getting-your-content-into-Edirom-Online) please name the edition _MyEdition_, set the publisher to _Editor_ and choose the image files to be exported, too. After export you should get the following example directory structure: + +* contents + * edition-MyEdition.xml + * sources + * edirom_source_[SourceID].xml + * … + * works + * edirom_work_[WorkID].xml + * … +* images + * edition-MyEdition + * edirom_source_[SourceID] + * [NameOfSourcePicture].jpg + * … + +Depending on the amount of data (structure and images), the export process could last for a while. Export is finished when you are see the library view of Edirom-Editor again. + +# Getting your content into Edirom Online +*(last modification of this section in the wiki 17.12.2015)* + +## Prerequisites + +This guide assumes that you have installed ["Edirom-Online as a service"](Getting-Edirom-Online) and prepared your content following the steps to get the example export data structure in ["Preparing your content for Edirom-Online"](Preparing-your-content-for-Edirom-Online). + +## Importing your edition's data to eXist-db + +* Open eXist-db's dashboard in your browser and authenticate as admin: _http://[localhost_or_IP]:8080_ +* Open _Collections_ to get access to the database contents. +* You should see three directories: _apps_, _contents_ and _system_. If there is no _contents_ directory, create it (third button in the toolbar). +* Go to _contents_ by double-clicking on it. +* Click on _Upload resources_ (last button in the toolbar) and then on _Upload_. Find your exported edition data and go to the there contained _contents_ directory. Choose your _edition-MyEdition.xml_ to be uploaded and do this again for the _sources_ and _works_ directories. + +## Importing your edition's image files to Digilib + +Copy the exported image files to Digilib: `sudo cp -R [PathToYourExportedData]/images/edition-MyEdition [PathToYourDigilib]/webapps/contents/images-100/`. + +You are now prepared to see your edition in Edirom-Online following [these steps](Getting-Edirom-Online#download-build-and-install-edirom-online). + +### Optional: Advanced image handling + +If you have followed the instructions for ["Edirom-Online as a service"](Getting-Edirom-Online#edirom-online-as-a-service), you will also have directories named _images-50_ and _images-25_ in your Digilib's _contents_ directory. Here you can store resized versions (50% and 25%) of your source images, which then will be selected by Digilib for loading when zoom levels are changed (e.g. in the source view of Edirom-Online). This function mainly accelerates image loading processes. + +If you want to use this function, resize the exported images with your preferred image processing application, preserving (!) the directory structure and file names. Copy these two new image sets to _images-50_ and _images-25_ the same way as described above. Edirom-Online will then be able to find the resized images on its own. If you want further information on this, please see Digilib's documentation on ["Directory layout for images"](http://digilib.sourceforge.net/image-directories.html). + From 3941cafd955ed293cb495abe5914a54539835f11 Mon Sep 17 00:00:00 2001 From: krHERO Date: Thu, 21 Nov 2024 13:08:13 +0100 Subject: [PATCH 7/7] Update README.md regarding documentation links this commit adds a subtopic "documentation" that links to /docs in this repo. addresses a comment by @peterstadler https://github.com/Edirom/Edirom-Online/pull/472#pullrequestreview-2447754151 Refs #https://github.com/Edirom/Edirom-Online/issues/415 --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 540505952..1c14d88cb 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ **[Showcases](https://github.com/Edirom/Edirom-Online#showcases) • [Get started](https://github.com/Edirom/Edirom-Online#get-started) • +[Documentation](https://github.com/Edirom/Edirom-Online#documentation) • [Dependencies](https://github.com/Edirom/Edirom-Online#dependencies) • [Roadmap](https://github.com/Edirom/Edirom-Online#roadmap) • [Contributing](https://github.com/Edirom/Edirom-Online#contributing) • @@ -97,6 +98,13 @@ When you have your system prepared with all Sencha Cmd prerequisites or you have * at `http://localhost:8080/exist/apps/dashboard/admin#` (signed-in) go to "Package Manager" then "Upload" and select the xar file which (supposed above build-method was used) was built at `/PATH_TO_LOCAL_EDIROM_EDITION_EXAMPLE_REPO/build/EditionExample-0.1.xar` * in **eXist-db Package Manager** click on the "Edirom Online" entry - you will be directed to the running Edirom at `http://localhost:8080/exist/apps/Edirom-Online/index.html` +## Documentation + +Some useful information regarding documentation is captured in the [docs] folder of this repo. It contains: +* [Customize] Edirom Online and content +* Edirom Online – [Release Workflow] +* [Setup Edirom Online] on a local machine + ## Dependencies Edirom Online depends heavily on the JavaScript framework [Ext JS] which is included in parts in our code base. We use Ext JS 4.2.1 in the GPL version. Edirom Online also includes the [Raphaël] javascript library (MIT License) and the [ACE] editor (BSD license). @@ -152,6 +160,10 @@ Edirom Online is released to the public under the terms of the [GNU GPL v.3] ope [Bargheer: Edition]: https://github.com/Edirom/Bargheer-Edition [eXist-db]: https://exist-db.org/ [Verovio]: https://www.verovio.org/index.xhtml +[docs]: /docs +[Customize]: docs/customize.md +[Release Workflow]: docs/release-workflow.md +[Setup Edirom Online]: docs/setup.md [Ext JS]: https://www.sencha.com/products/extjs [Raphaël]: http://raphaeljs.com [ACE]: http://ace.ajax.org