README.md

Islandora CWRC-Writer

Introduction

Provides a very minimal wrapper around the CWRC-Writer, so that it can be used in an Islandora context.

Requirements

This module requires the following modules/libraries:

• Islandora
• Islandora CWRC Document
• Islandora Rest
• Islandora Object Locking
• Libraries

The build directory contains the compiled version of the Islandora CWRC-Writer. It can also be built from the source, if NPM is installed.

Islandora CWRC-Writer is expected to be installed here:

• sites/default/modules/islandora_cwrc_writer/

Installation through NPM

1. Navigate to sites/default/modules/islandora_cwrc_writer/
2. Clone this repo: git clone https://github.com/cwrc/islandora_cwrc_writer.git
3. Install the dependencies: npm install
4. Run the build: npm run build

Updating

1. Navigate to sites/default/modules/islandora_cwrc_writer/
2. Get the latest changes: git pull
3. Clear the Drupal cache: drush cc all

Touchpoints between CWRC-Writer (JavaScript) and Islandora (cwrc/islandora_cwrc_writer Drupal Module)

Section goals:

• communicate the assumptions built into the integration module about how to interact with CWRC-Writer
• help determine whether or not a change to CWRC-Writer will be a breaking change to the integration module
• be updated as CWRC-Writer changes

The islandora_cwrc_writer modules uses code within the "theme", "utilities", and "js" directories to embed CWRC-Writer into a Drupal page by referencing items within the CWRC-Writer directory and overriding aspects (delegator to save/load docs).

1. islandora_cwrc_writer module loads files from within the CWRC-Writer library

   • CWRC-Writer treated as a self-contained library with the Drupal module loading specific files from specified internal CWRC-Writer directory locations (e.g., JS, CSS, etc)
   • If directories or filenames are changed then the Islandora integrated CWRC-Writer will break. Examples include
     • https://github.com/cwrc/islandora_cwrc_writer/blob/master/js/README.md
     • https://github.com/cwrc/islandora_cwrc_writer/blob/master/islandora_cwrc_writer.module#L12
     • https://github.com/cwrc/islandora_cwrc_writer/blob/master/includes/utilities.inc#L164-L165
     • https://github.com/cwrc/islandora_cwrc_writer/blob/master/includes/utilities.inc#L1091-L1097
     • https://github.com/cwrc/islandora_cwrc_writer/blob/master/islandora_cwrc_writer.install#L17
     • https://github.com/cwrc/islandora_cwrc_writer/blob/master/islandora_cwrc_writer.module#L274
     • list may not be exhustive - untested

2. Config parameters passed to CWRC-Writer

   • CWRC-GitWriter example: https://github.com/cwrc/CWRC-GitWriter/blob/master/src/js/config.js
     • set in islandora_cwrc_writer module by

       • Islandora-CWRC-Writer/includes/utilities.inc

         Lines 1088 to 1131 in 33c1209

         	$schemas = array();
         	foreach ($results as $result) {
         	$schema_object = islandora_object_load($result['pid']['value']);
         	if ($schema_object) {
         	// We shouldn't add schemas without CSS or SCHEMA datastreams; this could
         	// confuse CWRC-Writer.
         	if (!isset($schema_object['SCHEMA']) || !isset($schema_object['CSS'])) {
         	continue;
         	}
         	// template info.
         	$cwrc_writer_path = cwrc_libraries_get_path(ISLANDORA_CWRC_WRITER_LIB);
         	$entityTemplates = array(
         	'note' => file_create_url($cwrc_writer_path."/schema/".$result['mapping']['value']."/xml/".$result['entityTemplateNote']['value']),
         	'citation' => file_create_url($cwrc_writer_path."/schema/".$result['mapping']['value']."/xml/".$result['entityTemplateCitation']['value']),
         	);
         	// Base info.
         	$schema = array(
         	'pid' => $schema_object->id,
         	'name' => $result['label']['value'],
         	'schemaMappingsId' => $result['mapping']['value'],
         	'entityTemplates' => $entityTemplates,
         	);
         	// Determine where to set the RNG URL from.
         	if ($schema_object['SCHEMA']->controlGroup == 'X' || $schema_object['SCHEMA']->controlGroup == 'M') {
         	$schema['url'] = islandora_cwrc_writer_get_absolute_url("islandora/object/{$schema_object->id}/datastream/SCHEMA/view");
         	$schema['aliases'] = array(
         	// XXX: Generate an alias to match the old concatenated structure
         	// (without URL-encoding).
         	"$base_url/islandora/object/{$schema_object->id}/datastream/SCHEMA/view",
         	);
         	}
         	else {
         	$schema['url'] = $schema_object['SCHEMA']->url;
         	$schema['aliases'] = array($schema_object['SCHEMA']->url);
         	}
         	// Do the same for the CSS URL.
         	$schema['cssUrl'] = ($schema_object['CSS']->controlGroup == 'X' || $schema_object['CSS']->controlGroup == 'M') ?
         	islandora_cwrc_writer_get_absolute_url("islandora/object/{$schema_object->id}/datastream/CSS/view") :
         	$schema_object['CSS']->url;
         	// Add it to the list.
         	$schemas[$schema_object->id] = $schema;
         	}
         	}
         	return $schemas;

     • and passed to CWRC-Writer by

       • Islandora-CWRC-Writer/js/islandora_cwrc_writer.js

         Line 101 in 33c1209

         config = Drupal.settings.CWRCWriter;

3. Instantiate CWRC-Writer within the Drupal page

   • Islandora-CWRC-Writer/js/islandora_cwrc_writer.js

     Lines 233 to 271 in 33c1209

     	Drupal.CWRCWriter.writer = writer;
     	writer.event('writerInitialized').subscribe(function (writer) {
     	if (typeof config.initial_mode !== 'undefined') {
     	if (config.initial_mode == 'annotate') {
     	// writer.layoutManager.activateAnnotator();
     	writer.layoutManager.showModule('entities');
     	}
     	else if (config.initial_mode == 'read') {
     	// writer.layoutManager.activateReader();
     	writer.layoutManager.showModule('structure');
     	}
     	}
     	// Replace the show loader with our own function which can handle how we
     	// load documents, such that it will be drupal aware.
     	// broken by https://github.com/cwrc/CWRC-Writer/commit/c6c660bdba21c071098e76e3992e8a50a6658d39
     	//writer.dialogManager.filemanager.showLoader = Drupal.CWRCWriter.dialogManager.filemanager.showLoader($, writer);
     	// Log all loaded documents.
     	writer.event('documentLoaded').subscribe(function () {
     	// Update the select field with the new value if possible.
     	var $select = $('#islandora-cwrc-document-select'),
     	$navigation = $('#islandora-cwrc-document-nav');
     	$select.val(Drupal.CWRCWriter.writer.currentDocId);
     	$('li a', $navigation).removeClass('disabled');
     	if ($('option:selected', $select).is('option:last-child')) {
     	$('li.next a', $navigation).addClass('disabled');
     	}
     	if ($('option:selected', $select).is('option:first-child')) {
     	$('li.prev a', $navigation).addClass('disabled');
     	}
     	// Force resize, as it's needed when the layout is done in an iframe
     	// as it expects.
     	setTimeout(writer.layoutManager.resizeAll.bind(writer.layoutManager), 500);
     	});
     	writer.storageDialogs.load(writer);
     	});

4. Load and save the document

   • Islandora-CWRC-Writer/js/islandora_cwrc_writer.js

     Lines 114 to 171 in 33c1209

     	config.storageDialogs = {
     	save: function(writer) {
     	var docId = writer.currentDocId;
     	var docText = writer.converter.getDocumentContent(true);
     	$.ajax({
     	url : baseUrl+'editor/documents/'+docId,
     	type: 'PUT',
     	dataType: 'json',
     	data: {'doc':docText, 'schema':writer.schemaManager.schemas[writer.schemaManager.schemaId]['pid']},
     	success: function(data, status, xhr) {
     	writer.dialogManager.show('message', {
     	title : 'Document Saved',
     	msg : docId + ' was saved successfully.'
     	});
     	writer.event('documentSaved').publish();
     	},
     	error: function(xhr, status, error) {
     	displayError(xhr, docId);
     	}
     	});
     	},
     	load: function(writer) {
     	var docId;
     	if (config.documents.length) {
     	// Overlay can completely mangle the hash, so we can't rely on it.
     	docId = writer.currentDocId ? writer.currentDocId : config.documents[0];
     	}
     	if (docId != null) {
     	writer.currentDocId = docId;
     	writer.event('loadingDocument').publish();
     	$.ajax({
     	url: baseUrl+'editor/documents/'+docId,
     	type: 'GET',
     	success: function(doc, status, xhr) {
     	writer.converter.processDocument(doc, config.schemaId);
     	},
     	error: function(xhr, status, error) {
     	writer.dialogManager.show('message', {
     	title: 'Error',
     	msg: 'An error ('+status+') occurred and '+docId+' was not loaded.',
     	type: 'error'
     	});
     	writer.currentDocId = null;
     	writer.event('documentLoaded').publish(false, null);
     	},
     	dataType: 'xml'
     	});
     	} else {
     	writer.dialogManager.show('message', {
     	title: 'Error',
     	msg: 'No document to load',
     	type: 'error'
     	});
     	}
     	}
     	}

Java Servlet Configuration

CWRC-Writer depends on a number of Java Servlets to be functional.

• cwrc-validator

Follow the instructions on the page, but also rename the generated war to validator.war. In most cases your tomcat should exist here /usr/local/fedora/tomcat.

Reverse proxy config:

We make the assumption that we (reverse) proxy VIAF, to fix the same-origin issue.

For Apache, with Drupal running on the same box as Apache, a couple lines like:

ProxyPass /viaf http://www.viaf.org/viaf
ProxyPassReverse /viaf http://www.viaf.org/viaf

To be able to validate documents, we require that the validator.war is deployed to your tomcat directory, and that you set up a (reverse) proxy so that the CWRC-Writer can communicate with it.

ProxyPass /cwrc/services/validator/ http://localhost:8080/validator/
ProxyPassReverse /cwrc/services/validator/ http://localhost:8080/validator/

To be able to access Geonames service you must set up a proxy with authentication:

<Location /geonames>
   RequestHeader set Authorization "Basic XXXXX"
   ProxyPass http://apps.testing.cwrc.ca/cwrc-mtp/geonames/
   ProxyPassReverse http://apps.testing.cwrc.ca/cwrc-mtp/geonames/
</Location>

You'll need permission / authentication credentials from the CWRC organization. You can generation the credentials (replaces the XXXXX portion above) like so:

echo -n "username:password" | base64

In addition you must also enable mod_headers for the authentication credentials to be passed on to the CWRC Geonames service. With apache2 on Ubuntu this can be done like so:

sudo a2enmod headers
sudo service apache2 restart

Troubleshooting/Issues

Having problems or solved a problem? Contact discoverygarden.

Maintainers/Sponsors

Current maintainers:

• discoverygarden

Development

If you would like to contribute to this module, please check out our helpful Documentation for Developers info, Developers section on Islandora.ca and contact discoverygarden.

License

GPLv3