Visual Editor

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 of the load style menu item
		loadCSLName : "Load Style from Ref Manager",

		// Your function to load a CSL file into the editor
		loadCSLFunc : function () {
			alert("Loading a blank CSL style");
			cslEditor.setCslCode("<style><info /><citation><layout /></citation><bibliography><layout /></bibliography></style>");
		},

		// The name of the save/export style menu item
		saveCSLName : "Save Style to Ref Manager",

		// Your function to save/export a style out of the editor
		saveCSLFunc : function (cslCode) {
			alert("Save function not implemented");
		},

		onChange : function () {
			// this is called after every style edit.

			// 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

After you have instantiated a cslEditor object you can interact with it.

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.

Reading the data (proper API)