Visual Editor

How to use

This is the most basic javascript needed to use the Visual Editor.

	require.config({
		baseUrl: "..", // should be the path to cslEditorLib/
		urlArgs : "bust=$GIT_COMMIT"
	});
	requirejs(['src/config'], function (config) {
		require(['src/VisualEditor'], function (CSLEDIT_VisualEditor) {
			var cslEditor = new CSLEDIT_VisualEditor('#visualEditorContainer', { /* options go here */ });
		});
	});

Most of this is boilerplate needed for RequireJS, the interesting line is this:

	var cslEditor = new CSLEDIT_VisualEditor('#visualEditorContainer', { /* options go here */ });

This sets up the Visual Editor within the #visualEditorContainer div. See the 'Full configuration options' example below to see all possible options.

The Visual Editor uses persistent storage in the browser to retain state, see Storage.

Bare-bones example

A very basic example of it's use is the bare-bones example Visual Editor page.

Reference implementation

See the relevant files in the reference implementation for a more complete example:

• visualEditor/index.php
• src/visualEditorPage.js

Full configuration options example

Here's an example containing the complete list of options for the Visual Editor.

	var cslEditor = new CSLEDIT.VisualEditor("#visualEditorContainer", {
		// The name and function of the load style menu item
		loadCSLName : "Load Style from Ref Manager",
		loadCSLFunc : function () {
			alert("Loading a blank CSL style");
			cslEditor.setCslCode("<style><info /><citation><layout /></citation><bibliography><layout /></bibliography></style>");
		},

		// The name and function of the save/export style menu item
		saveCSLName : "Save Style to Ref Manager",
		saveCSLFunc : function (cslCode) {
			alert("Save function not implemented");
		},

		// Name and function of the load from URL menu item
		loadStyleFromUrlName : "Load Style From URL",
		loadStyleFromUrlFunc : function () {
			alert("Load from URL not implemented");
		},

		// this is called after every style edit
		onChange : function () {
			// you can access the current style contents using:
			var code = cslEditor.getCslCode();
		},
		
		// override the default initial style of APA with this:
		initialCslCode : "<style>this style is not valid!</style>",

		// each example reference follows the csl-data.json schema, but doesn't require the 'id' propery
		// (see https://github.com/citation-style-language/schema/blob/master/csl-data.json)
		exampleReferences : [
			{type:"article", title:"Article Title", author:"An Author", date:"2010"},
			{type:"book", title:"Book Title", author:"Another Author", date:"2000"}
		],

		// a list of the references to appear in each citation
		exampleCitations : [[0,1], [1]],

		onLoaded : function () {
			// do stuff after the UI has finished initializing
		}
	});

Interacting with the editor after instantiation

Tip: wait until it's loaded before doing anything, you can tell this by adding an onLoaded callback in the constructor options

Simple API

This is a currently limited set of the following helper functions:

	function setCslCode(cslCode)

This changes the CSL style code to cslCode.

If the return value contains error then an error occured - inspect the error object contents for more information.

	function getCslCode()

This gets the current CSL style code.

	function getStyleName()
	function getStyleId()
	function setStyleId(styleId)

Pretty self explanatory.

	function conformStyleToRepoConventions()

This checks if the style title, style ID, and rel=self link are consistent with the convention used for new styles in the CSL styles repo.

If they are not consistent, it will prompt the user to change them.

If the style name matches an already existing style, it will prompt the user to continue.

The return value will be false if the user doesn't wish to continue after prompting, true otherwise.

The internal API

To use the internal API functions, you need to require the appropriate module(s) first.

Here are a couple of examples, please browse the source code to learn more.

Reading the style contents

// note: src/dataInstance -> CSLEDIT_data is the only exception to 
//       the convention that the variable name always matches the 
//       module source code name, mainly because src/Data.js and 
//       src/data.js are the same file on windows
require(['src/dataInstance'], function (CSLEDIT_data) {
	// get all text nodes within the root of a macro node
	var textNodesInMacro = CSLEDIT_data.getNodesFromPath("style/macro/text");

	$.each(textNodesInMacro, function (i, node) {
		console.log("text node " + i + " has cslId: " + node.cslId);
	});
});

Changing the style

IMPORTANT: All style changes must go through src/controller if the Visual Editor UI is running.

require(['src/controller'], function (CSLEDIT_controller) {
	// There are only 5 possible commands to alter a style:

	// - addNode
	// - removeNode
	// - amendNode
	// - moveNode
	// - setCslCode

	// Use CSLEDIT_controller.exec(commandName, argumentList) to issue commands

	// See the corresponding function definition in 'src/Data' for the arguments in argumentList

	// e.g. add an empty macro node
	CSLEDIT_controller.exec("addNode", [0, "last", {name: "macro"}]);

	// To undo the last command
	CSLEDIT_controller.undo();

	// To redo a command you just undid
	CSLEDIT_controller.redo();
});

Changing the example citations

To debug or try out code in the console, wrapping all your calls in require() is a bit of a pain. Use CSLEDIT_expose to put modules into the global window namespace.

require(['src/exampleCitations'], function () {
	// let's see the JSON data for first reference in example citation 0
	var referenceIndexes = CSLEDIT_exampleCitations.getReferenceIndexesForCitation(0);

	console.log("Citation 0 contains the following references:");
	$.each(referenceIndexes, function (i, referenceIndex) {
		var referenceData = CSLEDIT_exampleCitations.getReferences()[referenceIndexes[0]];
		console.log("reference " + i + " is " + JSON.stringify(referenceData)); 
	});

	// this resets the exampleCitations to the default ones
	// (either the ones in src/exampleData, or the ones specified in the CSLEDIT_VisualEditor options)
	CSLEDIT.exampleCitations.resetToDefault();

	// takes same input as the exampleReferences constructor option
	CSLEDIT.exampleCitations.setReferences([
		{
			title : "reference 1"
		},
		{
			title : "reference 2"
		}
	]);

	// takes same input as the exampleCitations constructor option
	CSLEDIT.exampleCitations.setCitations([[0], [0,1]]);

	// Add a new reference to citation 2 (the 3rd one)
	CSLEDIT.exampleCitations.addReference(
		// argument 1 is a csl-data.json object
		// (see https://github.com/citation-style-language/schema/blob/master/csl-data.json)
		{
			title : "New reference",
			type: "article-journal"
		},
		// argument 2 (optional) is the index of the citation you want to add to
		2
	);
});