Django-CodeMirror is a Django application to embed the CodeMirror editor.
It was designed to be used in Sveetchies-documents, so it is suited for a ReStructuredText environment but CodeMirror support a large range of syntax coloration modes (PHP, Python, Ruby, Java, HTML, etc..). It is essentialy a jQuery plugin on top of CodeMirror to add some features like :
Your project will have to includes a copy of these Javascript libraries :
In your settings file add the app to your installed apps :
1 2 3 4 5 | INSTALLED_APPS = ( ... 'djangocodemirror', ... ) |
And you will need to have a copy of CodeMirror in your statics directory (see Django staticfiles). The jQuery library must be called by your templates, Django-CodeMirror don't do it for you.
DjangoCodeMirror is the jQuery plugin on top of CodeMirror, it accepts all CodeMirror options and some additional :
When the string is not empty, it is used as the URL to send data in POST request where the view receiver should save the data. This is disabled by default. If the csrf option is enabled, it will be used in the request.
The default sended datas are :
More datas can be sended with the quicksave_datas option.
Expect an object {...} whose variables will be sended as data in quicksave request.
Or it can be a string that determine a variable name to find the object in the global context. This is useful if you want to use a variable that can change and not a defined object at page load.
When the string is not empty, it is used as the URL to send data in POST request where the view receiver should render the content with a parser. The excepted response must return the HTML fragment rendered. This is disabled by default. If the csrf option is enabled, it will be used in the request.
The default sended datas are :
Expect a string containing the function name which be used to modify a request to add it the needed token by Django CSRF. The token will be injected in the request headers. A ready to use function is allready shipped.
The function have two required arguments :
You should see the option beforeSend of jQuery.axax() for more details, this is where the csrf function is really used.
A full example of these settings with the plugin :
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | <div> <textarea id="id_content" rows="10" cols="40" name="content"></textarea> <script language="JavaScript" type="text/javascript"> //<![CDATA[ my_datas = {'foo': 'bar'}; $(document).ready(function() { id_content_codemirror_instance = $('#id_content').djangocodemirror({ "mode": "rst", "csrf": "CSRFpass", "fullscreen": true, "help_link": "/help/", "quicksave_url": "/djangocodemirror-sample/quicksave/", "quicksave_datas": my_datas, "preview_url": "/djangocodemirror-sample/preview/", "display_cursor_position": true, "no_tab_char": true, "undo_buttons": true, "settings_cookie": "djancocodemirror_settings", "lineNumbers": true }); }); //]]> </script> </div> |
The plugin use some additional libraries (allready shipped) :
Note
If you directly use the plugin, you will have to load yourself all needed libaries, see Fields medias for a details of these.
This is the widget to use in your form fields to apply them an instance of DjangoCodeMirror or CodeMirror. It is accessible at djangocodemirror.fields.CodeMirrorWidget.
Usage example on a form field :
1 2 3 4 5 6 7 | from djangocodemirror.fields import CodeMirrorWidget class CodeMirrorSampleForm(forms.Form): content = forms.CharField(label=u"Your content", widget=CodeMirrorWidget) def save(self, *args, **kwargs): return |
The widget accept two additional arguments :
Another example where the content field will be a CodeMirror editor with enabled line numbers :
1 2 3 4 5 6 7 | from djangocodemirror.fields import CodeMirrorWidget class CodeMirrorSampleForm(forms.Form): content = forms.CharField(label="Your content", widget=CodeMirrorWidget(codemirror_only=True, codemirror_attrs={'lineNumbers':True})) def save(self, *args, **kwargs): return |
The widget load automatically all his needed medias and static files, you just have to put this in your templates :
{{ form.media }}
This behavior is inherited by DjangoCodeMirrorField and CodeMirrorField.
This inherit from django.forms.CharField to automatically use CodeMirrorWidget as the widget field. The widget set the codemirror_only attribute to True to use only the CodeMirror editor.
It take an additional named argument codemirror_attrs like CodeMirrorWidget, his default value correspond to the default setting of CODEMIRROR_SETTINGS.
1 2 3 4 5 6 7 8 | from django import forms from djangocodemirror.fields import CodeMirrorField class CodeMirrorSampleForm(forms.Form): content_codemirror = CodeMirrorField(label=u"Your content", codemirror_attrs={'lineNumbers':True}) def save(self, *args, **kwargs): return |
It is identical as CodeMirrorField but for usage of DjangoCodeMirror as the widget field.
His default value for codemirror_attrs correspond to DJANGOCODEMIRROR_DEFAULT_SETTING.
1 2 3 4 5 6 7 8 | from django import forms from djangocodemirror.fields import CodeMirrorField class CodeMirrorSampleForm(forms.Form): content_djangocodemirror = DjangoCodeMirrorField(label=u"Your content", codemirror_attrs={'lineNumbers':True}) def save(self, *args, **kwargs): return |
All default app settings is located in the settings_local.py file of djangocodemirror, you can modify them in your project settings.
Note
All app settings are overwritten if present in your project settings with the exception of dict variables. This is to be remembered when you want to add a new entry in a list variable, you will have to copy the default version in your settings with the new entry otherwise default variable will be lost.
Type : string
HTML code to instantiate CodeMirror in form fields, this is a template string (usable with String.format()) which expect two variable places :
Type : string
This identical to CODEMIRROR_FIELD_INIT_JS but for DjangoCodeMirror usage only.
Type : dict
The settings schemes to use with CodeMirror and DjangoCodeMirror editors. Each editor form fields use this schemes to get their default settings. Note that these options must be suitable to be transformed by the Python JSON parser.
The default available settings schemes are :
Type : string
The keyword to use to select the default settings with DjangoCodeMirrorField. Note that CodeMirrorField always use the keyword default to select his default settings.
Type : list or tuple
A list of paths for available translations.
Type : list or tuple
A list of paths for available themes to load with CodeMirror. There is actually no loaded theme by default, you will have to set one in your CODEMIRROR_SETTINGS
Type : list or tuple
A list of tuples for the various syntax coloration modes supported by CodeMirror. This list is generated from the available mode files in CodeMirror.
The CodeMirrorWidget widget need some medias to correctly load the editor, all these medias paths are defined in settings and you can change them if needed. Theses paths assume to be in your staticfiles directory (see Django staticfiles).
You can rapidly insert Django-CodeMirror in your project in adding djangocodemirror.urls to your project urls.py file. This will use djangocodemirror.views which contains the demonstration views.
1 2 3 4 5 | urlpatterns = patterns('', ... (r'^djangocodemirror-sample/', include('djangocodemirror.urls')), ... ) |
Three views are avalaible :
This application make usage of the Django internationalization system only in his demonstration. However the editor is translated with his own system using a javascript file for each available language.
To add a new language, you will have to add a new javascript file that will register the new available language. Just create a file with this :
1 2 3 | DCM_Translations["NAME"] = { // Translations goes here }; |
Where NAME is the language locale name to register and // Translations goes here must be replaced by the content to translate. To see a full translation see the french version in static/djangocodemirror/djangocodemirror.fr.js where you can see all the string to translate.
You can save your file where you want in your project or application, you will just have to register it in the setting DJANGOCODEMIRROR_TRANSLATIONS.