docs and setup.py updates
This commit is contained in:
Carl Meyer
parent
cfc195e6ef
commit
eb07823613
12
INSTALL.txt
12
INSTALL.txt
|
|
@ -1,12 +0,0 @@
|
|||
To install django-markitup, run the following command inside this
|
||||
directory:
|
||||
|
||||
python setup.py install
|
||||
|
||||
You can also just copy the included ``markitup`` directory somewhere
|
||||
on your Python path, or symlink to it from somewhere on your Python path;
|
||||
this is useful if you're working from a Subversion checkout.
|
||||
|
||||
This application requires Python 2.3 or later, and Django 1.0 or later.
|
||||
You can obtain Python from http://www.python.org/ and Django from
|
||||
http://www.djangoproject.com/.
|
||||
|
|
@ -1,7 +1,5 @@
|
|||
include AUTHORS.txt
|
||||
include CHANGELOG.txt
|
||||
include INSTALL.txt
|
||||
include LICENSE.txt
|
||||
include MANIFEST.in
|
||||
include README.txt
|
||||
recursive-include docs *
|
||||
152
README.txt
152
README.txt
|
|
@ -2,15 +2,151 @@
|
|||
django-markitup
|
||||
===============
|
||||
|
||||
This application provides convenient integration of the MarkItUp_
|
||||
markup editor widget (by Jay Salvat) in Django projects, via a custom
|
||||
form widget. It also provides server-side support for MarkItUp!'s
|
||||
AJAX preview.
|
||||
Easy integration of the MarkItUp_ markup editor widget (by Jay Salvat) in
|
||||
Django projects. Includes server-side support for MarkItUp!'s AJAX preview.
|
||||
|
||||
For installation instructions, see the file "INSTALL.txt" in this
|
||||
directory; for instructions on how to use this application, and on
|
||||
what it provides, see the file "overview.txt" in the "docs/"
|
||||
directory.
|
||||
|
||||
.. _MarkItUp: http://markitup.jaysalvat.com/
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Download a release tarball from Launchpad_, or get the Bazaar trunk
|
||||
version of the application::
|
||||
|
||||
bzr checkout lp:django-markitup django-markitup
|
||||
|
||||
To install django-markitup:
|
||||
|
||||
1. Put the ``markitup`` folder on your Python path (or use ``python
|
||||
setup.py install``, easy_install, or pip).
|
||||
|
||||
2. Add ``'markitup'`` to your ``INSTALLED_APPS`` setting (not actually
|
||||
necessary, but probably a good idea).
|
||||
|
||||
3. Make the contents of the "markitup/media/markitup" directory
|
||||
available at ``MEDIA_URL/markitup``. This can be done by copying the
|
||||
files, making a symlink, or through your webserver configuration.
|
||||
|
||||
4. If you want to use AJAX-based preview:
|
||||
|
||||
- Add ``url(r'^markitup/', include('markitup.urls')`` in your
|
||||
root URLconf.
|
||||
- Set the MARKITUP_PREVIEW_FILTER setting (see `Using AJAX preview`_
|
||||
below).
|
||||
|
||||
.. _Launchpad: http://launchpad.net/django-markitup
|
||||
|
||||
Using the MarkItUp! widget
|
||||
==========================
|
||||
|
||||
The MarkItUp! widget lives at ``markitup.widgets.MarkItUpWidget``, and
|
||||
can be used like any other Django custom widget.
|
||||
|
||||
To assign it to a form field::
|
||||
|
||||
from markitup.widgets import MarkItUpWidget
|
||||
...
|
||||
content = forms.TextField(widget=MarkItUpWidget())
|
||||
|
||||
When this form is displayed on your site, you must include the form
|
||||
media somewhere on the page using ``{{ form.media }}``, or the
|
||||
MarkItUpWidget will have no effect.
|
||||
|
||||
To use MarkItUpWidget in the Django admin:
|
||||
|
||||
from markitup.widgets import MarkItUpWidget
|
||||
|
||||
class MyModelAdmin(admin.ModelAdmin):
|
||||
...
|
||||
def formfield_for_dbfield(self, db_field, **kwargs):
|
||||
if db_field.name == 'content':
|
||||
kwargs['widget'] = MarkItUpWidget(attrs={'class': 'vLargeTextField'})
|
||||
return super(MyModelAdmin, self).formfield_for_dbfield(db_field, **kwargs)
|
||||
|
||||
You can also use the formfield_overrides attribute of the ModelAdmin, which
|
||||
is simpler but only allows setting the widget per field type (so it isn't
|
||||
possible to use the MarkItUpWidget on one TextField in a model and not
|
||||
another).
|
||||
|
||||
Choosing a MarkItUp! button set and skin
|
||||
========================================
|
||||
|
||||
MarkItUp! allows the toolbar button-set to be customized in a
|
||||
Javascript settings file. By default, django-markitup uses the
|
||||
"default" set (meant for HTML editing). Django-markitup also includes
|
||||
basic "markdown" and "textile" sets (these are the sets available from
|
||||
`the MarkItUp site <http://markitup.jaysalvat.com>`_, modified only to
|
||||
add previewParserPath).
|
||||
|
||||
To use an alternate set, assign the ``MARKITUP_SET`` setting a URL
|
||||
path (absolute or relative to MEDIA_URL) to the set directory. For
|
||||
instance, to use the "markdown" set included with django-markitup::
|
||||
|
||||
MARKITUP_SET = 'markitup/sets/markdown'
|
||||
|
||||
MarkItUp! skins can be specified in a similar manner. Both "simple"
|
||||
and "markitup" skins are included, by default "simple" is used. To
|
||||
use the "markitup" skin instead::
|
||||
|
||||
MARKITUP_SKIN = 'markitup/skins/markitup'
|
||||
|
||||
Neither of these settings has to refer to a location inside
|
||||
django-markitup's media. You can define your own sets and skins and
|
||||
store them anywhere, as long as you set the MARKITUP_SET and
|
||||
MARKITUP_SKIN settings to the appropriate URLs.
|
||||
|
||||
Set and skin may also be chosen on a per-widget basis by passing the
|
||||
``markitup_set`` and ``markitup_skin`` keyword arguments to
|
||||
MarkItUpWidget.
|
||||
|
||||
|
||||
Using AJAX preview
|
||||
==================
|
||||
|
||||
If you've included ``markitup.urls`` in your root URLconf (as
|
||||
demonstrated above under `Installation`_), all you need to enable
|
||||
server-side AJAX preview is the ``MARKITUP_PREVIEW_FILTER`` setting.
|
||||
|
||||
``MARKITUP_PREVIEW_FILTER`` must be a two-tuple.
|
||||
|
||||
The first element must be a string, the Python dotted path to a markup
|
||||
filter function. This function should accept markup as its first
|
||||
argument and return HTML. It may accept other keyword arguments as
|
||||
well. You may parse your markup for preview using any method you
|
||||
choose, as long as you can wrap it in a function that meets these
|
||||
criteria.
|
||||
|
||||
The second element must be a dictionary of keyword arguments to pass
|
||||
to the filter function. The dictionary may be empty.
|
||||
|
||||
For example, if you have python-markdown installed, you could use it
|
||||
like this::
|
||||
|
||||
MARKITUP_PREVIEW_FILTER = ('markdown.markdown', {'safe_mode': True})
|
||||
|
||||
Alternatively, you could use the "textile" filter provided by Django
|
||||
like this::
|
||||
|
||||
MARKITUP_PREVIEW_FILTER = ('django.contrib.markup.templatetags.markup.textile', {})
|
||||
|
||||
(The textile filter function doesn't accept keyword arguments, so the
|
||||
kwargs dictionary must be empty in this case.)
|
||||
|
||||
**Note:** If you use your own custom MarkItUp! set, be sure to set the
|
||||
``previewParserPath`` option to ``'/markitup/preview/'``.
|
||||
|
||||
|
||||
Other settings
|
||||
==============
|
||||
|
||||
MarkItUp! requires the jQuery Javascript library. By default,
|
||||
django-markitup links to the most recent minor version of jQuery 1.3
|
||||
available at ajax.googleapis.com (via the URL
|
||||
``http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js``).
|
||||
If you wish to use a different version of jQuery, or host it yourself,
|
||||
set the JQUERY_URL setting. For example::
|
||||
|
||||
JQUERY_URL = 'jquery.min.js'
|
||||
|
||||
This will use the jQuery available at MEDIA_URL/jquery.min.js.
|
||||
|
|
|
|||
|
|
@ -1,149 +0,0 @@
|
|||
===============
|
||||
django-markitup
|
||||
===============
|
||||
|
||||
Easy integration of the MarkItUp_ markup editor widget in Django projects.
|
||||
|
||||
|
||||
.. _MarkItUp: http://markitup.jaysalvat.com/
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Download a release tarball from Launchpad_, or get the Bazaar trunk
|
||||
version of the application::
|
||||
|
||||
bzr checkout lp:django-markitup django-markitup
|
||||
|
||||
To install django-markitup:
|
||||
|
||||
1. Put the ``markitup`` folder somewhere on your Python path.
|
||||
|
||||
2. Put ``'markitup'`` in your ``INSTALLED_APPS`` setting.
|
||||
|
||||
3. Make the contents of the "markitup/media/markitup" directory
|
||||
available at ``MEDIA_URL/markitup``. This can be done by copying the
|
||||
files, making a symlink, or through your webserver configuration.
|
||||
|
||||
4. If you want to use AJAX-based preview:
|
||||
|
||||
- Add ``url(r'^markitup/', include('markitup.urls')`` in your
|
||||
root URLconf.
|
||||
- Set the MARKITUP_PREVIEW_FILTER setting (see `Using AJAX preview`_
|
||||
below).
|
||||
|
||||
.. _Launchpad: http://launchpad.net/django-markitup
|
||||
|
||||
Using the MarkItUp! widget
|
||||
==========================
|
||||
|
||||
The MarkItUp! widget lives at ``markitup.widgets.MarkItUpWidget``, and
|
||||
can be used like any other Django custom widget.
|
||||
|
||||
To assign it to a form field::
|
||||
|
||||
from markitup.widgets import MarkItUpWidget
|
||||
...
|
||||
content = forms.TextField(widget=MarkItUpWidget())
|
||||
|
||||
When this form is displayed on your site, you must include the form
|
||||
media somewhere on the page using ``{{ form.media }}``, or the
|
||||
MarkItUpWidget will have no effect.
|
||||
|
||||
To use MarkItUpWidget in the Django admin:
|
||||
|
||||
from markitup.widgets import MarkItUpWidget
|
||||
|
||||
class MyModelAdmin(admin.ModelAdmin):
|
||||
...
|
||||
def formfield_for_dbfield(self, db_field, **kwargs):
|
||||
if db_field.name == 'content':
|
||||
kwargs['widget'] = MarkItUpWidget(attrs={'class': 'vLargeTextField'})
|
||||
return super(MyModelAdmin, self).formfield_for_dbfield(db_field, **kwargs)
|
||||
|
||||
You can also use the formfield_overrides attribute of the ModelAdmin, which
|
||||
is simpler but only allows setting the widget per field type (so it isn't
|
||||
possible to use the MarkItUpWidget on one TextField in a model and not
|
||||
another).
|
||||
|
||||
Choosing a MarkItUp! button set and skin
|
||||
========================================
|
||||
|
||||
MarkItUp! allows the toolbar button-set to be customized in a
|
||||
Javascript settings file. By default, django-markitup uses the
|
||||
"default" set (meant for HTML editing). Django-markitup also includes
|
||||
basic "markdown" and "textile" sets (these are the sets available from
|
||||
`the MarkItUp site <http://markitup.jaysalvat.com>`_, modified only to
|
||||
add previewParserPath).
|
||||
|
||||
To use an alternate set, assign the ``MARKITUP_SET`` setting a URL
|
||||
path (absolute or relative to MEDIA_URL) to the set directory. For
|
||||
instance, to use the "markdown" set included with django-markitup::
|
||||
|
||||
MARKITUP_SET = 'markitup/sets/markdown'
|
||||
|
||||
MarkItUp! skins can be specified in a similar manner. Both "simple"
|
||||
and "markitup" skins are included, by default "simple" is used. To
|
||||
use the "markitup" skin instead::
|
||||
|
||||
MARKITUP_SKIN = 'markitup/skins/markitup'
|
||||
|
||||
Neither of these settings has to refer to a location inside
|
||||
django-markitup's media. You can define your own sets and skins and
|
||||
store them anywhere, as long as you set the MARKITUP_SET and
|
||||
MARKITUP_SKIN settings to the appropriate URLs.
|
||||
|
||||
Set and skin may also be chosen on a per-widget basis by passing the
|
||||
``markitup_set`` and ``markitup_skin`` keyword arguments to
|
||||
MarkItUpWidget.
|
||||
|
||||
|
||||
Using AJAX preview
|
||||
==================
|
||||
|
||||
If you've included ``markitup.urls`` in your root URLconf (as
|
||||
demonstrated above under `Installation`_), all you need to enable
|
||||
server-side AJAX preview is the ``MARKITUP_PREVIEW_FILTER`` setting.
|
||||
|
||||
``MARKITUP_PREVIEW_FILTER`` must be a two-tuple.
|
||||
|
||||
The first element must be a string, the Python dotted path to a markup
|
||||
filter function. This function should accept markup as its first
|
||||
argument and return HTML. It may accept other keyword arguments as
|
||||
well. You may parse your markup for preview using any method you
|
||||
choose, as long as you can wrap it in a function that meets these
|
||||
criteria.
|
||||
|
||||
The second element must be a dictionary of keyword arguments to pass
|
||||
to the filter function. The dictionary may be empty.
|
||||
|
||||
For example, if you have python-markdown installed, you could use it
|
||||
like this::
|
||||
|
||||
MARKITUP_PREVIEW_FILTER = ('markdown.markdown', {'safe_mode': True})
|
||||
|
||||
Alternatively, you could use the "textile" filter provided by Django
|
||||
like this::
|
||||
|
||||
MARKITUP_PREVIEW_FILTER = ('django.contrib.markup.templatetags.markup.textile', {})
|
||||
|
||||
(The textile filter function doesn't accept keyword arguments, so the
|
||||
kwargs dictionary must be empty in this case.)
|
||||
|
||||
**Note:** If you use your own custom MarkItUp! set, be sure to set the
|
||||
``previewParserPath`` option to ``'/markitup/preview/'``.
|
||||
|
||||
|
||||
Other settings
|
||||
==============
|
||||
|
||||
MarkItUp! requires the jQuery Javascript library. By default,
|
||||
django-markitup links to the most recent minor version of jQuery 1.3
|
||||
available at ajax.googleapis.com (via the URL
|
||||
``http://ajax.googleapis.com/ajax/libs/jquery/1.3/jquery.min.js``).
|
||||
If you wish to use a different version of jQuery, or host it yourself,
|
||||
set the JQUERY_URL setting. For example::
|
||||
|
||||
JQUERY_URL = 'jquery.min.js'
|
||||
|
||||
This will use the jQuery available at MEDIA_URL/jquery.min.js.
|
||||
3
setup.py
3
setup.py
|
|
@ -2,8 +2,9 @@ from setuptools import setup, find_packages
|
|||
|
||||
setup(
|
||||
name='django-markitup',
|
||||
version='0.2.2dev',
|
||||
version='0.2.2',
|
||||
description='Django integration with the MarkItUp universal markup editor',
|
||||
long_description=open('README.txt').read(),
|
||||
author='Carl Meyer',
|
||||
author_email='carl@dirtcircle.com',
|
||||
url='http://launchpad.net/django-markitup',
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user