It is possible that plugins may be added back in the future, but as of right now there is no working plugin feature. All following documentation only pertains to versions 0.6.0 and earlier.
django-scribbler editor has some nice features like a live preview, auto-saving drafts and tab completion of template tags and template context. If you find yourself wanting to extend the functionality of the editor or top menu you can write a plugin.
Client-side plugins to be added to a scribbler/js/plugins folder inside of
static files folder. If you are writing this plugin for a reusable application
then it would live inside of the app’s static folder. The plugin name
will be the name of the .js file. For example we might create a demo plugin
by adding a scribbler/js/plugins/demo.js inside of our app static folder.
django-scribbler uses RequireJS to load its Javascript requirements. Since this code is loaded in a closure, plugins need to be written in the AMD format. The basic format is:
define(function () {
function plugin(editor, menu) {
// Plugin code goes here...
}
return plugin;
});
This has an advantage in that the plugin code can declare requirements as well as take advantage of existing modules used by the scribbler code. For instance if your plugin requires jQuery you can define the requirement:
define(['jquery'], function ($) {
function plugin(editor, menu) {
// Plugin code goes here...
}
return plugin;
});
The plugin code itself should return a function which takes two arguments: editor
and menu. Each are the current instance of the editor and the menu respectively.
Within the plugin you can add additional controls or event bindings. The APIs for
both the editor and the menu are given below.
Note
The plugins are executed after the editor and menu have been initialized but they are loaded asynchronously. That means the editor and menu may be fully rendered before the plugins are executed.
Plugins are enable by listing them in a data-scribbler-plugins attribute on the
script tag:
<script data-scribbler-plugins="themes"
data-main="{{ STATIC_URL }}scribbler/js/scribbler{% if not debug %}-min{% endif %}"
src="{{ STATIC_URL }}scribbler/libs/require.js"></script>
If mutliple plugins used then they should be comma seperated as in
data-scribbler-plugins="themes,other".
Note
Since the plugins are loaded asynchronously they might not load in the same order they are listed. Plugins should be written and designed with that limitation in mind.
As noted above you can use the define call to load additional dependencies/libraries
for your plugin from the set of libraries used by django-scribbler. The available libraries
are:
The editor passed in the plugin is an instance of the ScribbleEditor defined
in scribbler/js/scribbler-editor.js. Below is a list of some of the most relevant
functions and properties for controlling the editor.
editor.scribbles¶This is a jQuery object containing all of the scribble divs available on the page for editting.
A jQuery object for the div wrapping all of the editor button controls (Save, Save Draft, Discard Draft, Close). If you want to add additional controls they should be appended here.
editor.editor¶editor.editor is the instance of the CodeMirror editor. You can manipulate this
object to change the options with editor.editor.setOption. See the CodeMirror
usage manual for available options: http://codemirror.net/doc/manual.html
editor.open(scribble)¶Opens the editor to edit the given scribble.
editor.close()¶Closes the editor.
editor.submitPreview(force)¶Submits the current editor content to render the live preview. By default this
will not submit if the editor is currently in the process of rendering a preview.
Passing true into the call will force the submission.
editor.submitSave()¶Submits the editor content to save the current scribble content. By default the save will not be submitted if the last preview was not valid.
editor.getFormData()¶Prepares the current form data for preview/save submission. If you want to pass additional data to the server your plugin could extend this function.
editor.createDraft()¶Saves the current editor content as a local draft.
editor.restoreDraft()¶Restores the editor content from the last saved draft if available.
editor.deleteDraft()¶Discards last saved draft.
editor.setStatus(msg)¶Displays a status message to the user in the header of the editor.
editor.destroy()¶Removes the editor from the DOM and unbinds all event handling.