README

An ARCHE dissemination service providing mapping of resource's metadata to BibLaTeX bibliographic entries.

Installation

Run in the webserver docroot:

composer require acdh-oeaw/arche-biblatex
ln -s vendor/acdh-oeaw/arche-biblatex/index.php index.php
cp vendor/acdh-oeaw/arche-biblatex/config-sample.yaml config.yaml

Adjust config.yaml

Usage

http://deploymentUrl/?id=url-encoded-arche-resource-identifier&lang=preferredLanguageCode

Optionally an override query parameter can be also supplied providing URL-encoded BibLaTeX bibliographic entry or its fragment. It works in the same way as an override coming from ARCHE resource metadata (details below), just is applied after it.

Override rules

The base BibLaTeX bibliographic entry is created according to the mapping provided in the config.yaml. The mapping is chosen based on the ARCHE resource RDF class.
Then overrides comming from the ARCHE resource metadata property specified by the config.yaml->biblatex->biblatexProperty configuration option are applied.
Finally overrides comming from the override request parameter are applied.

Details

All bibliographic entry information including entry type and citation key are overrided. If you want to preserve the entry type and/or citation key:
- either use the "magic" NOOVERRIDE type/citation key value, e.g.
```
@NOOVERRIDE{NOOVERRIDE,
  fieldToOverride = {overriding value},
}
```
- or provide just BibLaTeX fields skipping the bibliographic entry header (and the final curly bracket), e.g.
```
fieldToOverride = {overriding value},
```
If you want a field to be skipped from the output, override it with an empty value.

Example

Compare the output for the sample resource (https://hdl.handle.net/21.11115/0000-000E-753C-C).
(please note the same data which are provided in the override request parameter below can be also provided in the "custom citation" resource metadata property)

Default: https://arche-biblatex.acdh.oeaw.ac.at/?lang=en&id=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000E-753C-C`
With entry type set to book but citation key preserved, author field overrided with a new value as well as booktitle and bookauthor fields removed: https://arche-biblatex.acdh.oeaw.ac.at/?lang=en&id=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000E-753C-C&override=%40book%7BNOOVERRIDE%2C%0A%20%20author%20%3D%20%7BDoe%2C%20John%7D%0A%2C%20%20booktitle%20%3D%20%7B%7D%2C%20bookauthor%20%3D%20%7B%7D%2C%0A%7D
The non-URL-encoded override parameter value () used here is:
```
@book{NOOVERRIDE,
  author = {Doe, John},
  booktitle = {},
  bookauthor = {},
}
```
With author field overrided with a new value as well as booktitle and bookauthor fields removed. As automatically created entry type and citation key are to be kept, a short syntax skipping the BibLaTeX entry header is used. https://arche-biblatex.acdh.oeaw.ac.at/?lang=en&id=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000E-753C-C&override=author%20%3D%20%7BDoe%2C%20John%7D%0A%2Cbooktitle%20%3D%20%7B%7D%2Cbookauthor%20%3D%20%7B%7D%2C The non-URL-encoded override parameter value () used here is:
```
author = {Doe, John},  
booktitle = {}, 
bookauthor = {},
```

Docker deployment

The build/docker directory contains a Dockerfile defining a runtime environment for the service.

It takes one build argument VARIANT which can be either production or development and affects the PHP ini settings - see the Configuration section of the https://hub.docker.com/_/php.

It expects all the service files (including composer libraries and the desired config.yaml) to be provided in build/docroot during the build time.

For a live development you can just build it with an empty build/docroot directory and mount service files during docker run.

Examples:

Creating a production image

# install dependencies skipping development ones and optimizing autoloader
composer update --no-dev -o
# prepare the docroot using build/config/arche.yaml as the config.yaml
mkdir build/docroot && cp -R index.php src vendor build/docroot/ && cp build/config/arche.yaml build/docroot/config.yaml
# build the image
docker build --rm -t acdhch/arche-biblatex --build-arg VARIANT=production build
# try to run it locally
docker run -d --name arche-biblatex -p 80:80 acdhch/arche-biblatex
# check if it works locally
curl -i 'http://127.0.0.1/?id=https%3A%2F%2Fid.acdh.oeaw.ac.at%2Fgtrans'
# push the image to the registry
docker push acdhch/arche-biblatex
# redeploy on ACDH Kubernetes
curl -X POST 'https://rancher.acdh-dev.oeaw.ac.at/v3/project/{pathToDesiredWorkload}?action=redeploy' -H 'Authorization: Bearer {myRancherApiToken}'

Creating a development image and running it locally

# install dependencies
composer update
# prepare an empty docroot
mkdir build/docroot
# build the image
docker build --rm -t acdhch/arche-biblatex:dev --build-arg VARIANT=development build
# run the image using current directory as a docroot making it available on local port 8080
docker run -d --name arche-biblatex -p 8080:80 -v `pwd`:/var/www/html acdhch/arche-biblatex:dev
# check if it works
curl -i 'http://127.0.0.1:8080/?id=https%3A%2F%2Fid.acdh.oeaw.ac.at%2Fgtrans'

acdh-oeaw / arche-biblatex

Maintainers

Details

README

Installation

Usage

Override rules

Details

Example

Docker deployment