search

pkiraly / qa-catalogue-web

QA Catalogue / A data quality dashboard for MARC catalogues
GNU General Public License v3.0
10 stars 6 forks source link
code4lib metadata-qa-marc solr

readme

QA Catalogue Web

A data quality dashboard for library catalogues

Output sample

This application provides a web interface for searching, browsing, and displaying QA Catalogue data from library catalogues for quality analysis and statistics of metadata.

Catalog information is made available from CSV files, JSON files, SQLite database, images, and a Solr search index. The reports are made accessible using a Web browser and has been implemented by PHP and JavaScript.

Table of Contents

Installation

In the following:

Analyse your catalog using the QA Catalogue Backend) and the result will be saved in $DATADIR/$CATALOG and a Solr index.

Download

Install this software into a web server with PHP enabled such as (Apache or Nginx with PHP-FPM).

Create a temporary directory and download the current version to an application directory served by your webserver (here we use /var/www/html/$APPDIR):

mkdir tmp
cd tmp
wget https://github.com/pkiraly/qa-catalogue-web/archive/master.zip
unzip master.zip
mv metadata-marc-web-master /var/www/html/$APPDIR

or clone the git repository:

git clone https://github.com/pkiraly/qa-catalogue-web.git /var/www/html/$APPDIR
cd /var/www/html/$APPDIR

# optionally checkout a tagged release
git checkout v0.7.0

Requirements:

sudo apt install locales gettext php-sqlite3 php-yaml php-curl composer
sudo locale-gen en_GB.UTF-8
sudo locale-gen de_DE.UTF-8
sudo locale-gen pt_BR.UTF-8
sudo locale-gen hu_HU.UTF-8

Setup

Change into the application directory:

cd /var/www/html/$APPDIR

Install PHP dependencies and create required cache directories and permissions:

composer install

The script will further tell you to change ownership of directories if the application is served as wwww-data but installed as another user.

If you also want to locally change the source code (see contributing), allow www-data to get the current state of the working directory:

sudo -u www-data git config --global --add safe.directory "$PWD"

Configuration

A configuration file in INI format is required. Prepare configuration file:

echo "dir=$DATADIR" > configuration.cnf

The catalogue class should explicitly be specified:

echo "catalogue=$CATALOG" >> configuration.cnf

Additional configuration parameters are listed below. Data type and version number when the parameter was introduced are given in parentheses:

The following parameters can be set either for all catalogues (parameter=value) or for each individual catalogue (parameter[id]=...).

The parameter include can be used to include another configuration file and merge its parameters into the base configuration. Recursive inclusion is not supported and include is ignored if the referenced file does not exist.

Multiple catalogues can be configured in one file. To do so, add an individual catalogue id in brackets after a configuration field to override its default value. For instance if versions=false is a general setting, while versions[loc]=false is a library specific setting.

Example:

id=bvb
display-network=0
indexName[bvb]=bayern
dirName[bvb]=bayern

setup additional directories and permissions:

sudo chgrp www-data -R _smarty cache
ln -s $DATADIR/[catalogue]/img images/[catalogue]

On Apache webserver add these lines to its configuration (/etc/apache2/sites-available/000-default.conf):

<Directory /var/www/html/$CATALOG>
  AllowOverride All
  Order allow,deny
  allow from all
</Directory>

If you don't want the application to check version number from local git repository, create a (possibly empty) configuration file version.ini. The file can also be generated with composer run git-version.

echo "catalogue=$CATALOG" >> configuration.cnf

Finally you can access the application at http://localhost/$APPDIR.

Customization

Templates

Some parts of the web interface can be customized with local files in directory config (not existing by default) or another directory configured with parameter templates:

Catalogue class

The name, catalogue link and the record level catalogue link are different per libraries. The tool has prepared for a number of libraries, but there's high chance, that you would like to apply it for another library.

Basic properties and default configuration settings are defined in a catalogue class which extends the generic class Catalogue. Such a class enables you to define additional changes that go beyond simple configuration settings.

Here is an example of a custom catalogue class:

class Gent extends Catalogue {

  protected $name = 'gent';
  protected $label = 'Universiteitsbibliotheek Gent';
  protected $url = 'https://lib.ugent.be/';
  protected $marcVersion = 'GENT';

  function getOpacLink($id, $record) {
    return 'https://lib.ugent.be/catalog/rug01:' . trim($id);
  }
}

$url contains an URL of the catalogue in the library website, $marcVersion is the abbreviation of MARC version used in the analyses.

Please create a new file in the directory classes/catalogue. You do not have to do any other registration. The convention is that the name of the class is the first upper case form of the name property (Gent - gent, Cerl - cerl) etc. The later should fit the data directory name, the Solr index name, and either the application path or the catalogue property of the configuration. $url contains an URL of the catalogue in the library website, $marcVersion is the abbreviation of MARC version used in the analyses.

Translation

Now the user interface is translatable via gettext methods. We provide two language files (German and English). In .tpl files you can add translatable text as

{_('translatable text')}

_ is a built-in alias for the PHP function gettext. If there are variables in the translated string, in the .tpl file you should use the _t function, defined by the project, like this:

{_t('number of records: %d', $number_of_records)}

You should add the translations into locale/de_DE/LC_MESSAGES/messages.po as

msgid "translatable text"
msgstr "übersetzbarer Text"

and into locale/en_GB/LC_MESSAGES/messages.po as

msgid "translatable text"
msgstr "translatable text"

If the message string contain variables, use sprintf compatible placeholders, such as '%d' for integers, '%s' for strings, '%f' for floating point numbers etc.

msgid "Found <span id=\"numFound\">%s</span> records"
msgstr "Found <span id=\"numFound\">%s</span> records"

Of course the message identifier could be different, and dense but now I think that it is more understandable (so translatable) this way. When you add a translation please add a comment to denote which page the original text appears, such as

# completeness
msgid "by document types"
msgstr "nach Dokumenttypen"

Once you have done, you should generate the .mo files from the .po files with the following command:

composer run translate

If translations have been changed, Webserver or FastCGI respectively may need to be restarted to clear the translation cache, e.g.

sudo service apache2 restart

Please let us know if you would like to see more languages supported.

Troubleshouting: if the translation would not work you can check if a given language (locale) is available in your system. In Linux you can check it with

locale -a

If the locale (e.g. 'de_DE.UTF-8') is not available, you can install it with

locale-gen de_DE.UTF-8

The tool supports the following languages:

Note: translation is in a very early phase, not all the text of the user interface are translatable, and translations are not equally covering the original texts.

Maintainers

QA Catalogue Web is developed by Péter Király and Jakob Voß.

Please notify us if you would like to use it. Happy searching!

Contributing

QA Catalogue Web is managed in a public git repository at pkiraly/qa-catalogue-web. Contributions are welcome!

To ensure code quality run the following tasks:

License

GNU General Public License - GPLv3