Getting Started

Getting Started

Some tips to help find your way around the code.

cslEditorLib Directory structure

• content/ Just the newStyle.csl template at present.

• css/ The .css style files.

• docs/ A submodule containing this wiki documentation.

• 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.

To reconfigure

This needs to be done if you update the 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.

RequireJS and jQuery

The code uses jQuery extensively and RequireJS for module dependencies. The code will make a lot more sense if you familiarise yourself with these.

• jQuery
• RequireJS

Coding conventions

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

• When requiring a module with filename FILENAME, it's 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());
			}
		});
	});

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

Data storage

The src/storage module wraps localStorage to provide persistent storage for the editor. The different pages use the storage as follows:

• Search by Name and Search by Example

  • Not used in the core library, although the reference implementation uses it when the Edit button is pressed to store the style before opening the Visual Editor page.

• Visual Editor

  • The CSL data
  • The example citations metadata and options
  • An alternative CSL schema (experimental: you can set an alternative schema on the settings page)
  • The state of the layout panes

• Code Editor

  • The CSL data

You can view and reset the current local storage from the settings page.