Djiffy Documentation¶
Contents:
Django application to index and display IIIF Manifests for books
djiffy is intended to be a reusable Django application for working with digitized book-like content provided via IIIF Presentation manifests. This is an alpha version and it does not yet support the full IIIF Presentation specification.
Note
djiffy is tested against Django 4.1-5.2 and Python 3.9-3.11.
Code documentation is available at https://princeton-cdh.github.io/djiffy/
Installation¶
Use pip to install:
pip install djiffy
You can also install from GitHub. Use a branch or tag name, e.g.
@develop or @1.0, to install a specific tagged release or branch:
pip install git+https://github.com/Princeton-CDH/djiffy.git@develop#egg=djiffy
Configuration¶
Add djiffy to installed applications and make sure that django.contrib.humanize is also enabled:
INSTALLED_APPS = (
...
'django.contrib.humanize',
'dal',
'dal_select2',
'djiffy',
...
)
Include the default djiffy urls at the desired base url with the namespace djiffy:
urlpatterns = [
...
url(r'^iiif-books/', include('djiffy.urls', namespace='djiffy')),
...
]
Run migrations to create database tables:
python manage.py migrate
Note
The templates included require that you have a url configured with
the name site-index.
If you are need to use djiffy to access manifests that require an authorization token, use DJIFFY_AUTH_TOKENS in your project settings to configure each domain that requires an auth token. The configuration should be formatted like this:
DJIFFY_AUTH_TOKENS = {
'example.com': 'myauthtoken',
}
Usage¶
Import IIIF content using the import_manifest manage command. This command can take an IIIF Collection or single Manifest, via local file or URL. Imported content can be viewed in Django admin.:
python manage.py import_manifest http://url.for/iiif/manifest
python manage.py import_manifest /path/to/local/collection
Development instructions¶
This git repository uses git flow branching conventions.
Initial setup and installation:
recommended: create and activate a python 3.9 virtualenv:
virtualenv djiffy -p python3.9 source djiffy/bin/activate
pip install the package with its python dependencies:
pip install -e .
Unit Testing¶
Unit tests are written with py.test but use some Django test classes for convenience and compatibility with django test suites. Running the tests requires a minimal settings file for Django required configurations.
Copy sample test settings and add a SECRET_KEY:
cp ci/testsettings.py testsettings.py
To run the tests, either use the configured setup.py test command:
python setup.py test
Or install test requirements and use py.test directly:
pip install -e '.[test]' pytest
Documentation¶
Documentation is generated using sphinx. To generate documentation, first install development requirements:
pip install -r dev-requirements.txt
Then build documentation using the customized make file in the docs directory:
cd sphinx-docs
make html
As of v0.7.3, documentation is automatically built with GitHub Actions and published using GitHub pages.
Adding license images¶
When adding new license image SVG files to this repo, add id="licenseimg" to
the <svg> element of each. This allows djiffy users to embed the SVG inline
with a <use> tag, with its href attribute pointing to #licenseimg.
If the image will need to be recolored for different backgrounds, as in the
case of the rightsstatement_org/ SVG icons, you can enable this for up to
two tones in each SVG. To do this, set fill attributes on paths to
fill="inherit" (controlled by the fill CSS property) or
fill="currentColor" (controlled by the color CSS property).
License¶
djiffy is distributed under the Apache 2.0 License.
©2024 Trustees of Princeton University. Permission granted via Princeton Docket #20-3618 for distribution online under a standard Open Source license. Ownership rights transferred to Rebecca Koeser provided software is distributed online via open source.
