Difference between revisions of "Community/Community resources/Development"

Latest revision as of 07:12, 10 September 2024

Main Page > Community > Community/Community resources > Community/Community resources/Development

In this section of the wiki, we'll add links to custom patches, plugins, themes, images, forks, and other resources developed by community users and publicly available for developers to explore and work with.

AtoM 2.7 Drupal 9 feed module

Developed by members of the University of Toronto (U of T) Libraries, this AtoM Drupal importer is a Drupal 9 module based on the AtoM API. The module is used at U of T to facilitate publishing archival description once, in U of T's Discover Archives (AtoM) finding aid database, after which it pulls description data into Drupal as Nodes and Taxonomies. This data can then generate a searchable collections list (A-Z) in Drupal as well as a Drupal page per top-level fonds/collections. When data in the linked AtoM instance is updated or new data is added, the module can also fetch and update the Drupal data at a designated frequency.

The goal of the module is to reuse published AtoM description metadata in a more end-user-friendly Drupal website to facilitate "general user" browse/discovery of top-level descriptions on the University's Drupal-based departmental websites, where users may not normally encounter the archival AtoM instance.

You can see an example of the module in use on the U of T's Media Commons Archives Drupal website , displaying data from their AtoM descriptions.

You can find this plugin at:

• https://github.com/utlib/drupal_atom

It has been confirmed to work with AtoM 2.7.x.

This work was originally shared in the AtoM User Forum on November 16, 2023:

• https://groups.google.com/g/ica-atom-users/c/aCAdGKdFgNQ/m/E14KAUOKBAAJ

Initial module planning, creation, and development included:

• Rachel Beattie, Assistant Media Archivist
• Gordon Belray, Information Architect
• Andy Foster, Senior Software Engineer
• Lillian Hogendoorn, Curator of Digital Experience
• Bilal Khalid, Manager of Digital Library Applications
• Sunny Lee, Digital Initiatives Programmer Analyst
• Christina Stewart, Assistant Media Archivist
• Chul Hee Yoon, Project Application Programmer Analyst
• Kelli Babcock, Digital Initiatives Librarian

AtoM 2.4 Drupal front-end display bridge

Michael Andreae of the University of Toronto has created a fork of Drupal's Views Database Connector that has been modified to work as a bridge for AtoM, so that Drupal can be used as a public-facing front-end. From the README on the GitHub project:

Views Database Connector is a powerful module that gives Views full access to external database tables found in the settings for your Drupal installation. With this module, you can setup a view around any table in any database configuration. This can be extremely useful to pull external data from a database to show to your users in a view.

The Drupal AtoM connector is a non generalized version of Views Database Connector, VDC was just used as a template. In Drupal you can create blocks and add whatever sections you need based on an object.

For example adding in a fonds you can link another view in fields of notes types and then link based on id. Because there can be multiple notes etc... on one record it was easier to add the relations in the Drupal View rather than in the Database Connector.

According to notes on the README, this bridge has only been tested with AtoM version 2.4.0 - 156.

The code, along with basic installation instructions, can be found on GitHub, here:

• https://github.com/Vic-Lib/DrupalAtoMViewer

AtoM Linux Installer scripts

Community user Guillermo Castellano Casas has developed some automated bash installation scripts that can be used to install AtoM 2.4, 2.5, or 2.6. Below are the GNU/Linux distributions currently supported for each AtoM version:

• 2.6: Ubuntu 18.04, Debian 10.
• 2.5: Ubuntu 16.04/18.04, Debian 9.
• 2.4: Ubuntu 16.04.

• The GitLab repository where the scripts and basic usage instructions can be found: here
• A contributor's guide if you'd like to help improve the installers!
• The AtoM user forum post where these were first shared with the AtoM community (September 2019)

AtoM virtual machines

Community user Ricardo Pinho has prepared a webite, atom-vm.com, where he is sharing production-ready virtual machine (VM) images of AtoM releases. Intended for use either as local development environments or in production for small to medium archives, these VMs are built using the recommended AtoM installation instructions.

As of November 2023 the site currently hosts Virtual Machines for:

(Release 2.5.4) - AtoM-VM 2.5.4;

(Release 2.6.4) - AtoM-VM 2.6.4;

Other versions will be added in the future.

Ricardo asks for a small donation to support the site and future releases. To run the VMs you will first need to install any Virtual Machine player able to import the standard ovf and vmdk file format or run directly from a vmx file - examples include Virtualbox or the free VMWare Player. At this time, the current release of AtoM-VM runs only on 64-bit computers (x86-amd64). For more information, see:

• atom-vm.com

CENDARI Shibboleth authentication plugin

CENDARI (Collaborative European Digital Archive Infrastructure) is a research collaboration aimed at integrating digital archives and resources for research on medieval and modern European history. They have chosen AtoM for use as their collaborative Archival Directory (site here, more information here), and have done some custom development, including a plugin to integrate with Shibboleth, an "open-source project that provides Single Sign-On capabilities and allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner."

The plugin was developed against AtoM 2.1, and has had compatibility updates for 2.3. In 2019, a community user has also reported success in the User forum using this plugin with a 2.4.1 release. Another user forked the plugin, added a few additional commit (details here and here), and reports it working with those changes in a 2.6.4 release. Status of testing against other releases is unknown.

The original plugin development was done by Carsten Thiel, primarily between November and December of 2014.

• GitHub repository
• Plugin documentation

PeaceWorks MAID plugins

NOTE: As of 2024-09, these plugins have been upgraded to work with 2.8.x AtoM installations

In March of 2015, PeaceWorks Technology Solutions helped to launch MAID (Mennonite Archival Image Database), a collaborative project of the Mennonite Historical Society of Canada which includes Mennonite archival partners in British Columbia, Alberta, Saskatchewan, Manitoba, and Ontario, with images held in a shared AtoM instance. Over the course of the 2-year design and development project leading up to the launch, PeaceWorks developed several custom features and plugins for use in MAID, including an eCommerce "shopping cart" plugin for purchasing prints of images available in MAID; an image carousel for the home page; integration with TinyMCE to add a WYSIWYG set of editing tools to AtoM's static pages (e.g. so users did not need to know basic HTML to style static pages); and the ability to upload a different watermark (to be applied to digital object derivatives) for each institution. More details on each below.

eCommerce plugin

This plugin has been developed by Jason Hildebrand of PeaceWorks Technology Solutions, primarily between July 2014 and March 2015.

According to the plugin documentation's Overview section, "This plugin allows website visitors to select and purchase individual photos. Payment for the photos happens via PayPal. E-Commerce admins review each order and may approve or reject (remove) photos from the order. After approval, the customer is sent an email containing a link which they can use to download the image(s).

Users have access to a shopping cart, where photos from multiple repositories can be added as users browse the site, and then ordered/checked out via PayPal. The shopping cart has basic integration with AtoM's PREMIS rights module, so when Dissemination = "Disallow," a message about restrictions is supplied instead. Other features include a vacation setting and a sales report.

• PeaceWorks GitHub AtoM fork, eCommerce branch
• eCommerce plugin documentation
• MAID, where you can see the shopping cart in action

MAID has also prepared a summary description of the plugin's functionality, available as a PDF here:

• File:Ecommerce-MAID.pdf (PDF, approx 431KB)

Home page carousel plugin

This plugin has been developed by Jason Hildebrand of PeaceWorks Technology Solutions, primarily between July 2014 and March 2015.

This plugin adds a slideshow to the AtoM front page which displays up to 30 of the most recently added/updated photos in the system. Photos and their captions (if available) are displayed. Users may click a photo to go to its archival description.

• PeaceWorks GitHub AtoM fork, Carousel branch
• Carousel README documentation
• MAID homepage, where you can see the carousel in action

TinyMCE visual editor integration for editing static pages

This integration has been developed by Jason Hildebrand of PeaceWorks Technology Solutions, primarily between April 2014 and March 2015. At this time, this integration has not been packaged as a plugin.

TinyMCE is " a platform independent web based Javascript HTML WYSIWYG editor control released as Open Source under LGPL," that, when integrated with AtoM, allows users unfamiliar with HTML to style static pages using familiar buttons, tools, and other user interface elements. The integration includes basic text styling (bold, underline, italics), table creation, image and file upload, link creation, and more.

• PeaceWorks GitHub AtoM fork, TinyMCE branch
• TinyMCE README documentation

Per-institution watermarks for digital objects

This integration has been developed by Jason Hildebrand of PeaceWorks Technology Solutions, between July 2014 and March 2015 (primarily in July 2014). At this time, this integration has not been packaged as a plugin.

AtoM includes the little-known ability to apply a watermark to uploaded photos. However there is only provision for a single global watermark which is applied to all images. This customization allows each institution to have their own watermark, and institutional watermarks can be uploaded and managed via the user interface, in the archival institution's "Edit theme" page. Uploading a new watermark will not affect photos already present in AtoM, but AtoM does provide a way for a developer to cause all watermarks to be re-applied (see “Regenerating Derivatives” in the Command-line tools section of the Administrator's Manual of the AtoM documentation for more details).

• Peaceworks GitHub AtoM fork, multiple-watermarks branch
• the commit with the changes
• Multiple watermarks README documentation

Docker and AtoM

Two different community developers have combined AtoM with Docker, an open, container-based virtualization platform for distributed applications. Details below.

AtoM Docker Files

Created by Dominic Boisvert (@DominicBoisvert) for use in an archival course taught at the University of Montreal, Boisvert has shared Docker files for AtoM 2.1.2, and ICA-AtoM 1.3.2, including simple installation instructions (written in French):

• AtoM 2.1.2 Dockerfile
• ICA-AtoM 1.3.2 Dockerfile

AtoM Docker Compose recipe

Created by John Fink (@jbfink), this is a Docker Compose recipe for AtoM. Compose is described by Docker as "a tool for defining and running multi-container applications with Docker. With Compose, you define a multi-container application in a single file, then spin your application up in a single command which does everything that needs to be done to get it running."

The developer adds, "Note that I've only tested this on 64bit native Linux using Docker directly, so if you're using boot2docker or a VM things might be different." For further configuration information and troubleshooting, see the README provided.

• Docker Compose recipe for AtoM - GitHub repository
• README file for configuration and troubleshooting
• Related AtoM User Forum thread

AtoM Docker Image

Created by the Governo Regional Azores, this is a Docker image of AtoM 2.2.0. Note that it does not currently include the MySQL database required for AtoM, which needs to be linked.

• Link on the DockerHub page
• GitHub repository for the Docker image

AtoM 2.3 ISO image - ready for use on a flash drive

A group of archivists in Brazil, the Grupo de Pesquisa do CNPq GED/A e Patrimônio Documental Arquivístico, have used the SystemBack backup management tool to prepare an ISO image of AtoM 2.3 that can be launched from a flash drive. From the related blog post:

• Operating System: Ubuntu 16.04 - 64 Bits;
• Size: 3GBs
• Format: sblive
• Remasterer: SystemBack

"After Download, use SystemBack to write to the flash drive, and use with a system boot that is persistent - your data stored in the session will remain available in the next.'"

• Ubuntu Linux password: icaatom99
• User in AtoM (ICA-AtoM): GrupoCNPqDocsDigitais@gmail.com
• Password in AtoM (ICA-AtoM): icaatom

• Blog post here (Brazilian Portuguese): http://documentosarquivisticosdigitais.blogspot.com.br/2017/01/o-grupo-de-pesquisa-cnpq-ufsm-geda.html
• Download link: https://drive.google.com/file/d/0BwBRoubj23bpNWZLSVhtSmNoN00/view?usp=sharing

HTML scrub scripts for other entities

In Release 2.2 we introduced HTML escaping as part of the security enhancements included in the release. Since some users might have legacy HTML content in their descriptions, we also included a command-line task that would allow users to scrub legacy HTML from archival descriptions - see the related documentation here.

However, this task only currently works for archival descriptions. To help clean up other entities, users from Brazil have adapted versions of the original task that can be run for actors, notes, repository records, and rights records. These were posted in the AtoM user forum on 2017-05-22:

• https://groups.google.com/d/msg/ica-atom-users/_xdBK0ucegg/RQnNM5DKBAAJ

Artefactual has not tested these scripts. To run them:

1. Download and unzip the rar file attached to the message in the user forum.
2. Place the scripts in a directory accessible from the root directory of your AtoM instance, such as a new tmp directory.
3. Use the tools:run command to run each script. For example, for the script to clean up HTML in authority records:

php symfony tools:run tmp/actor_i18n.php

The effects will be similar to what is described for the command-line task:

• https://www.accesstomemory.org/docs/latest/admin-manual/maintenance/cli-tools/#remove-html-content-from-archival-description-fields

Custom theme plugins

This section will be a place for community members to share any theme plugins they have developed! Note that we have documentation and slides to help developers get started with theming - be sure to check them out, as well as our general Development resources!

Alberto Pereira's custom theme

Developed against AtoM 2.5, this custom theme by Alberto Pereira includes a number of customizations, including the following change notes from the developer:

• The "Popular this week" box gets a bigger highlight;
• The first element of the "Popular this week" also shows its thumbnail (if it exists);
• Overall style changes (including new icons);
• A Blog! (well, sort of), it uses static pages to mimic a blog. You just have to create a page called "Blog", and any other page that has a title that starts with "_X-", will automatically be listed in the blog page (e.g. "_X-A post title");
• You don't have to chose between the sidebar treeview and the full width treeview. You can have both. There's a new link, right below the sidebar treeview, that opens a popup with the full width treeview.

An image of the arAPPlugin theme

You can find the theme and more details at the following links:

• Theme code, images, and installation instructions on GitHub
• AtoM user forum announcement (2019-02-27)

• Back to Community resources
• Back to Community landing page
• Main AtoM wiki page