This repository contains the data platform for the research project OwnReality. Jedem seine Wirklichkeit. Der Begriff der Wirklichkeit in der Bildenden Kunst in Frankreich, BRD, DDR und Polen der 1960er bis Ende der 1980er Jahre (website in German) by Dr. Mathilde Arnoux at the German Centre for Art History Paris. The project was funded by the European Research Council.
During the course of the project, data was gathered and entered into a database. In general, this platform allows the integration of that data into web based systems such as content management systems. To be independent of the target technology, the integration is implemented with a set of customized html tags with no assumptions on lower layers. An API-only web application retrieves the data from an elasticsearch instance and relays to the widgets.
For legal reasons, the image data cannot be made available publicly. Please contact Dr. Mathilde Arnoux (firstname.lastname@example.org) if you would like to have access to the additional media.
This documentation aims to provide information on:
- the requirements to run the application
- how to set up the API-application
- importing the data from the included json documents
- importing the additional image data
- how to integrate the widgets on a third-party page
We will just list the requirements here because their installation procedures are documented nicely on their respective pages. The versions indicate tested compatibility.
- linux (not a requirement but this howto assumes linux)
- elasticsearch (7.10.2)
- ruby (2.6.6)
- nodejs (12.20.1), only for building
The API is a rails application that can be deployed under a ruby web server, the phusion passenger apache module, the phusion passenger nginx module or a combination of the above. For simplicity's sake, we will concentrate on a setup under the ruby application server.
Navigate to the folder where the application should reside and unpack the sources there:
mkdir -p /var/www/rack cd /var/www/rack wget https://github.com/moritzschepp/ownreality/archive/master.tar.gz tar xzf master.tar.gz mv ownreality-master ownreality cd ownreality
With ruby installed, proceed by installing the
gem install bundler
This will allow you to fetch all other gems required for the app and install them into a local directory:
bundle install --path=./bundled_gems
And finally copy the default configuration file
cp config/app.yml.example config/app.yml
npm install npm run build
The built version will be placed at public/app.js within the app's directory.
The json data is available at https://ownreality.dfkg.org/data.js.tar.gz. Please download the archive to the application directory, e.g.
tar xzf /root/json.data.tar.gz
The json files include the metadata for the platform but they have to be imported. The environment variable tells rails that it should run in the production environment where some optimizations apply. So then, run
RAILS_ENV=production bundle exec rake or:from_json
If you received a copy of the image data, you should have an additional tarball. Simply unpack it within the application directory (e.g.):
tar xzf /root/ownreality_media.tar.gz
The application will work without this last step but the user will be shown placeholders instead of the actual media.
Running the app
Now you can run the application:
RAILS_ENV=production bundle exec puma
Simply go to http://127.0.0.1:9292 with your browser and you should see a demo page integrating a subset of the available widgets.
Running the tests
The app comes with a small test suite. Since the behavior partly depends on how the app is integrated within the deployment environment, the test suite tests the production page by default. Run it like this:
bundle exec rails test -v test/system
Using the widgets
because that allows you to use the custom tags anywhere on the page. It doesn't
matter how you place the content. This can be a static html page or a page
managed with a content management system. Note that the
has to be set to the url where the app was deployed to.
<or-language-selector></or-language-selector>: lets the user select the content language. If you set the attribute locales, the widget will change from a select box to a set of buttons allowing switches between those languages instead of the default (de, fr, en).
<or-busy-wheel></busy-wheel>: shows a spinning wheel as an indicator while data is being loaded
<or-general-filters></or-general-filters>: query input, time slider, people (facets) and attribute (facets), requires attributes or-base-target-attribs-url and or-base-target-people-url each indicating the target link url for the respective facet groups.
<or-results></or-results>: displays the tabbed result panel, the widget or-general-filters is required on the same page
<or-filtered-chronology></or-filtered-chronology>: displays the chronology results for the current search, the widget or-general-filters is required on the same page
<or-item-list type="magazines"></or-item-list>: shows the full list of magazines. You may also use “articles” or “interviews” instead of “magazines”.
<or-chronology-ranges></or-chronology-ranges>: shows a list of links (one for each year)
<or-chronology-results></or-chronology-results>: shows the chronology results according to the selected year, the widget or-chronology-ranges is required on the same page
<or-list-item></or-list-item>shows an individual item as within the search results, required attributes: id (the id of the object to display, e.g. “23258”) type (can have values “articles”, “sources”, “interviews” or "magazines")
<or-item></or-item>shows an individual item as inline as possible. required attributes: id (the id of the object to display), type (magazines or articles or interviews). By default, the items title is shown as a link to a dialog that shows more detail. You may specify label which will show that information instead. If you set or-search-url to an url, then the widget will assume that there is a working search on that page; on click, the user will be switching to that search page with this item preconfigured as criterion (currently only works for the magazines type)