{ "info": { "author": "Shaun Sephton & Piotr Malinski", "author_email": "riklaunim@gmail.com", "bugtrack_url": null, "classifiers": [ "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Topic :: Internet :: WWW/HTTP :: Dynamic Content" ], "description": "Django CKEditor\n===============\n\n**NOTICE: django-ckeditor 5 has backwards incompatible code moves against 4.5.1.**\n\n\nFile upload support has been moved to ckeditor_uploader. The urls are in ckeditor_uploader.urls, while for the file uploading widget you have to use RichTextUploadingField instead of RichTextField.\n\n\n**Django admin CKEditor integration.**\nProvides a ``RichTextField``, ``RichTextUploadingField``, ``CKEditorWidget`` and ``CKEditorUploadingWidget`` utilizing CKEditor with image uploading and browsing support included.\n\nThis version also includes:\n\n#. support to django-storages (works with S3)\n#. updated ckeditor to version 4.9\n#. included all ckeditor language and plugin files to made everyone happy! ( `only the plugins maintained by the ckeditor develops team `__ )\n\n.. contents:: Contents\n :depth: 5\n\nInstallation\n------------\n\nRequired\n~~~~~~~~\n#. Install or add django-ckeditor to your python path.\n ::\n\n pip install django-ckeditor\n\n#. Add ``ckeditor`` to your ``INSTALLED_APPS`` setting.\n\n#. Run the ``collectstatic`` management command: ``$ ./manage.py collectstatic``. This will copy static CKEditor required media resources into the directory given by the ``STATIC_ROOT`` setting. See `Django's documentation on managing static files `__ for more info.\n\n#. CKEditor needs to know where its assets are located because it loads them\n lazily only when needed. The location is determined in the ``ckeditor-init.js``\n script. and defaults to ``static/ckeditor/ckeditor/``. This does not work all\n the time, for example when using ``ManifestStaticFilesStorage``, any asset\n packaging pipeline or whatnot. django-ckeditor is quite good at automatically\n detecting the correct place even then, but sometimes you have to hardcode\n ``CKEDITOR_BASEPATH`` somewhere. This can be hardcoded in settings, i.e.::\n\n CKEDITOR_BASEPATH = \"/my_static/ckeditor/ckeditor\"\n\n It is possible to override\n the ``admin/change_form.html`` template with your own if you really need to do\n this, i.e.::\n\n {% extends \"admin/change_form.html\" %}\n\n {% block extrahead %}\n \n {{ block.super }}\n {% endblock %}\n\n Of course you should adapt this snippet to your needs when using\n CKEditor outside the admin app.\n\n\nRequired for using widget with file upload\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n#. Add ``ckeditor_uploader`` to your ``INSTALLED_APPS`` setting.\n\n#. Add a ``CKEDITOR_UPLOAD_PATH`` setting to the project's ``settings.py`` file. This setting specifies a relative path to your CKEditor media upload directory. CKEditor uses Django's storage API. By default, Django uses the file system storage backend (it will use your ``MEDIA_ROOT`` and ``MEDIA_URL``) and if you don't use a different backend you have to have write permissions for the ``CKEDITOR_UPLOAD_PATH`` path within ``MEDIA_ROOT``, i.e.::\n\n CKEDITOR_UPLOAD_PATH = \"uploads/\"\n\n When using default file system storage, images will be uploaded to \"uploads\" folder in your ``MEDIA_ROOT`` and urls will be created against ``MEDIA_URL`` (``/media/uploads/image.jpg``).\n\n If you want be able for have control for filename generation, you have to add into settings yours custom filename generator::\n\n # utils.py\n\n def get_filename(filename):\n return filename.upper()\n\n ::\n\n # settings.py\n\n CKEDITOR_FILENAME_GENERATOR = 'utils.get_filename'\n\n CKEditor has been tested with django FileSystemStorage and S3BotoStorage.\n There are issues using S3Storage from django-storages.\n\n#. For the default filesystem storage configuration, ``MEDIA_ROOT`` and ``MEDIA_URL`` must be set correctly for the media files to work (like those uploaded by the ckeditor widget).\n\n#. Add CKEditor URL include to your project's ``urls.py`` file::\n\n url(r'^ckeditor/', include('ckeditor_uploader.urls')),\n\n#. Note that by adding those URLs you add views that can upload and browse through uploaded images. Since django-ckeditor 4.4.6, those views are decorated using ``@staff_member_required``. If you want a different permission decorator (``login_required``, ``user_passes_test`` etc.) then add views defined in ``ckeditor.urls`` manually to your urls.py.\n\n#. Set ``CKEDITOR_IMAGE_BACKEND`` to one of the supported backends to enable thumbnails in ckeditor gallery. By default no thumbnails are created and full size images are used as preview. Supported backends:\n\n - ``pillow``: Uses Pillow\n\n\n\nOptional - customizing CKEditor editor\n--------------------------------------\n\n#. Add a CKEDITOR_CONFIGS setting to the project's ``settings.py`` file. This specifies sets of CKEditor settings that are passed to CKEditor (see CKEditor's `Setting Configurations `__), i.e.::\n\n CKEDITOR_CONFIGS = {\n 'awesome_ckeditor': {\n 'toolbar': 'Basic',\n },\n }\n\n The name of the settings can be referenced when instantiating a RichTextField::\n\n content = RichTextField(config_name='awesome_ckeditor')\n\n The name of the settings can be referenced when instantiating a CKEditorWidget::\n\n widget = CKEditorWidget(config_name='awesome_ckeditor')\n\n By specifying a set named ``default`` you'll be applying its settings to all RichTextField and CKEditorWidget objects for which ``config_name`` has not been explicitly defined ::\n\n CKEDITOR_CONFIGS = {\n 'default': {\n 'toolbar': 'full',\n 'height': 300,\n 'width': 300,\n },\n }\n\n It is possible to create a custom toolbar ::\n\n CKEDITOR_CONFIGS = {\n 'default': {\n 'toolbar': 'Custom',\n 'toolbar_Custom': [\n ['Bold', 'Italic', 'Underline'],\n ['NumberedList', 'BulletedList', '-', 'Outdent', 'Indent', '-', 'JustifyLeft', 'JustifyCenter', 'JustifyRight', 'JustifyBlock'],\n ['Link', 'Unlink'],\n ['RemoveFormat', 'Source']\n ]\n }\n }\n\n If you want or need plugins which are not part of django-ckeditor's\n plugin set you may specify assets and plugins as follows::\n\n text = RichTextField(\n config_name='forum-post',\n\n # CKEDITOR.config.extraPlugins:\n extra_plugins=['someplugin'],\n\n # CKEDITOR.plugins.addExternal(...)\n external_plugin_resources=[(\n 'someplugin',\n '/static/.../path-to-someplugin/',\n 'plugin.js',\n )],\n )\n\n\nOptional for file upload\n~~~~~~~~~~~~~~~~~~~~~~~~\n#. All uploaded files are slugified by default. To disable this feature, set ``CKEDITOR_UPLOAD_SLUGIFY_FILENAME`` to ``False``.\n\n#. Set the ``CKEDITOR_RESTRICT_BY_USER`` setting to ``True`` in the project's ``settings.py`` file (default ``False``). This restricts access to uploaded images to the uploading user (e.g. each user only sees and uploads their own images). Upload paths are prefixed by the string returned by ``get_username``. If ``CKEDITOR_RESTRICT_BY_USER`` is set to a string, the named property is used instead. Superusers can still see all images. **NOTE**: This restriction is only enforced within the CKEditor media browser.\n\n#. Set the ``CKEDITOR_BROWSE_SHOW_DIRS`` setting to ``True`` to show directories on the \"Browse Server\" page. This enables image grouping by directory they are stored in, sorted by date.\n\n#. Set the ``CKEDITOR_RESTRICT_BY_DATE`` setting to ``True`` to bucked uploaded files by year/month/day.\n\n#. You can set a custom file storage for CKEditor uploader by defining it under ``CKEDITOR_STORAGE_BACKEND`` variable in settings.\n\n\nUsage\n-----\n\nField\n~~~~~\nThe quickest way to add rich text editing capabilities to your models is to use the included ``RichTextField`` model field type. A CKEditor widget is rendered as the form field but in all other regards the field behaves as the standard Django ``TextField``. For example::\n\n from django.db import models\n from ckeditor.fields import RichTextField\n\n class Post(models.Model):\n content = RichTextField()\n\n**For file upload support** use ``RichTextUploadingField`` from ``ckeditor_uploader.fields``.\n\n\nWidget\n~~~~~~\nAlernatively you can use the included ``CKEditorWidget`` as the widget for a formfield. For example::\n\n from django import forms\n from django.contrib import admin\n from ckeditor.widgets import CKEditorWidget\n\n from post.models import Post\n\n class PostAdminForm(forms.ModelForm):\n content = forms.CharField(widget=CKEditorWidget())\n class Meta:\n model = Post\n\n class PostAdmin(admin.ModelAdmin):\n form = PostAdminForm\n\n admin.site.register(Post, PostAdmin)\n\n**For file upload support** use ``CKEditorUploadingWidget`` from ``ckeditor_uploader.widgets``.\n\n\nOutside of django admin\n~~~~~~~~~~~~~~~~~~~~~~~\n\nWhen you are rendering a form outside the admin panel, you'll have to make sure all form media is present for the editor to work. One way to achieve this is like this::\n\n
\n {{ myform.media }}\n {{ myform.as_p }}\n \n
\n\nor you can load the media manually as it is done in the demo app::\n\n {% load static %}\n \n \n\nWhen you need to render ``RichTextField``'s HTML output in your templates safely, just use ``{{ content|safe }}``, `Django's safe filter `_\n\n\nManagement Commands\n~~~~~~~~~~~~~~~~~~~\nIncluded is a management command to create thumbnails for images already contained in ``CKEDITOR_UPLOAD_PATH``. This is useful to create thumbnails when using django-ckeditor with existing images. Issue the command as follows::\n\n $ ./manage.py generateckeditorthumbnails\n\n**NOTE**: If you're using custom views remember to include ckeditor.js in your form's media either through ``{{ form.media }}`` or through a ``