Getting Started

Some tips to help find your way around the code.

Directory structure

• content/ Just the newStyle.csl template at present.
• css/ The .css style files.
• exampleCitationsGenerator/ A node.js script for generating example citations using all the styles in the csl-styles repository.
• external/ All external dependencies go here.
• generated/ All files generated from configure.sh, including the CSL schema in .rng format and example formatted citations in every style.
• html/ Html content (all retreived using AJAX calls at present).
• pages/ To open in your browser. Example bare-bones versions of the four pages, a settings page, and test pages.
• src/ The javascript source files.

Javascript modules

For dynamically generated documentation, point your browser to pages/sourceDocumentation.html

• The code uses RequireJS for module dependencies.

• Each .js file except config.js contains a RequireJS module definition.

• When used, modules are always given the variable name CSLEDIT_$FILENAME. e.g. in the following module definition, src/controller.js is loaded as variable CSLEDIT_controller:

	require(['src/controller'], function (CSLEDIT_controller) {
		// Add an empty 'macro' node
		CSLEDIT_controller.exec("addNode", [0, "last", {name: macro, attributes: [], children: []} ]);
	});

• Modules starting with a capital letter are constructor functions, modules starting with a lower case letter are global instances. e.g.:

	define(['src/storage', 'src/VisualEditor'], function (CSLEDIT_storage, CSLEDIT_VisualEditor) {
		// CSLEDIT_storage is a global instance
		CSLEDIT_storage.clear();

		// CSLEDIT_VisualEditor is a constructor function which requires instantiation
		var visualEditor = new CSLEDIT_VisualEditor(new CSLEDIT_VisualEditor('#visualEditorContainer', {
			onLoaded : function () {
				alert("Loaded visualEditor. Current style id is " + visualEditor.getStyleId());
			}
		});
	});

Tip: when debugging in the console, you can use a shorter notation to gain access to a module:

	// you can use this...
	require('src/controller').undo();

	// ...instead of this
	require(['src/controller'], function (CSLEDIT_controller) {
		CSLEDIT_controller.undo();
	});

Coding Style

• node-jshint is used to ensure a reasonably consistent coding style, there's a .jshintrc with the options.

Reconfiguring

This only needs to be done if you change external/csl-styles or external/csl-schema submodules or any code affecting the example citation generation.

• Run configure.sh

This does the following:

1. Converts the CSL schema files in cslEditorLib/external/csl-schema to .rng format.
2. Generates example citations and bibliographies for all the styles in cslEditorLib/external/csl-styles using the reference metadata in cslEditorLib/src/exampleData.js

All output goes into the generated/ directory, which is checked in to the repository for convenience.

Common Issues with configure.sh

• The configuration script runs successfully with up-to-date packages and node.js v6.9.1 (installed via nvm) on Ubuntu 16.10
• Issue "The 'gyp==0.1' distribution was not found and is required by the application" is typically due to python library intefering with the gyp command. See e.g. here.
• Issue "Citeproc initialisation exception: TypeError: child.getAttribute is not a function" signals an issue with the DOM parser used in citeproc.js. It should not occur with the most recent version
• Issue “FATAL ERROR: JS Allocation failed - process out of memory” is due to node.js running out of memory. The configure script currently assigns 5GB(!) of memory to node when generating the citation styles, which seems to work. Eventually, a more memory-concious process should be used.