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.
PLEASE NOTE: Artefactual does not test these features and modules developed by AtoM community members. As such, we cannot offer support for them, nor can we speak as to their security, quality, performance, or compatibility with the latest public releases. If you intend to make use of these features, do so at your own risk. We strongly recommend studying the code prior to use, and deploying any community-developed features in a test environment where they can be properly evaluated.
Have you developed custom code for your AtoM installation? Let us know! And... why not consider contributing your code to the public project? That way, we maintain the code for you through future releases, and the entire community benefits from your work! Here are some links to get you started:
- 1 AtoM Drupal front-end display bridge
- 2 AtoM Linux Installer scripts
- 3 AtoM virtual machines
- 4 CENDARI Shibboleth authentication plugin
- 5 PeaceWorks MAID plugins
- 6 Docker and AtoM
- 7 AtoM 2.3 ISO image - ready for use on a flash drive
- 8 HTML scrub scripts for other entities
- 9 Custom theme plugins
AtoM 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:
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 July 17, 2020, the site currently hosts Virtual Machines for:
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:
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. Status of testing against other releases is unknown. The development was done by Carsten Thiel, primarily between November and December of 2014.
PeaceWorks MAID plugins
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.
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 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.
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.
Did you know? As of the AtoM 2.3 release, the AtoM project now has its own officially supported Docker Compose development environment! See:
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 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.
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:
- User in AtoM (ICA-AtoM):
- Password in AtoM (ICA-AtoM):
- 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
UPDATE: Thanks to collaboration among several community members, this work has now been added to the existing AtoM task, and merged into the 2.4 release. For more information, see:
- Source pull request: https://github.com/artefactual/atom/pull/568
Thank you to Clara Rosales and Darryl Friesen for this collaborative enhancement!
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:
Artefactual has not tested these scripts. To run them:
- Download and unzip the rar file attached to the message in the user forum.
- Place the scripts in a directory accessible from the root directory of your AtoM instance, such as a new tmp directory.
- 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:
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.
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)