Welcome to django-inplaceedit’s documentation!

Getting started

Information

Inplace Edit Form is a Django application that allows you to inline edition of some data from the database

It is distributed under the terms of the GNU Lesser General Public License <http://www.gnu.org/licenses/lgpl.html>

Demo

Video Demo, of django-inplaceedit and Django-inlinetrans (Set full screen mode to view it correctly)

https://github.com/django-inplaceedit/django-inplaceedit/raw/master/video-frame.png

Usage

Calling inplace_edit tag you can inplace edit any data from the database. It is important to clarify that the inline edition is not only for text fields, although it may be the more common usage. You can also have inline edition for choices, boolean fields, date and datetime fields, foreing keys, many to many, file and image fields.

{% inplace_edit  "OBJ.FIELD_NAME" %}
{% inplace_edit  "OBJ.FIELD_NAME|FILTER1|FILTER2|...|FILTERN" %}

You only should change this:

<span>{{ user.first_name }}</span>
<span>{{ user.last_name }}</span>

to this:

<span>{% inplace_edit  "user.first_name" %}</span>
<span>{% inplace_edit  "user.last_name" %}</span>

Install

Requirements

  • Django (>= 1.2, even works with 1.1 with some customizations in your project)
  • jQuery (>=1.6)

In your base.html

Add

{% load inplace_edit %}

and wherever you load your static files, add either

{% inplace_toolbar %}

or

{% inplace_static %}

In your settings.py

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.admin',

    #.....................#

    'inplaceeditform',
)

And uncomment the request context processor:

TEMPLATE_CONTEXT_PROCESSORS = (
    #...#
    'django.core.context_processors.request',
    #...#
)

Optional:

INPLACEEDIT_EDIT_EMPTY_VALUE = 'Double click to edit'
INPLACEEDIT_AUTO_SAVE = True
INPLACEEDIT_EVENT = "dblclick"
INPLACEEDIT_DISABLE_CLICK = True  # For inplace edit text into a link tag
INPLACEEDIT_EDIT_MESSAGE_TRANSLATION = 'Write a translation' # transmeta option
INPLACEEDIT_SUCCESS_TEXT = 'Successfully saved'
INPLACEEDIT_UNSAVED_TEXT = 'You have unsaved changes'
INPLACE_ENABLE_CLASS = 'enable'
DEFAULT_INPLACE_EDIT_OPTIONS = {} # dictionnary of the optionals parameters that the templatetag can receive to change its behavior (see the Advanced usage section)
DEFAULT_INPLACE_EDIT_OPTIONS_ONE_BY_ONE = True # modify the behavior of the DEFAULT_INPLACE_EDIT_OPTIONS usage, if True then it use the default values not specified in your template, if False it uses these options only when the dictionnary is empty (when you do put any options in your template)
ADAPTOR_INPLACEEDIT_EDIT = 'app_name.perms.MyAdaptorEditInline' # Explain in Permission Adaptor API
ADAPTOR_INPLACEEDIT = {'myadaptor': 'app_name.fields.MyAdaptor'} # Explain in Adaptor API
INPLACE_GET_FIELD_URL = None # to change the url where django-inplaceedit use to get a field
INPLACE_SAVE_URL = None # to change the url where django-inplaceedit use to save a field

In your urls.py

urlpatterns = patterns('',

    #...#

    (r'^inplaceeditform/', include('inplaceeditform.urls')),

    #...#
)

If you use the date adaptor or datetime adaptor also:

js_info_dict = {
    'packages': ('django.conf',),
}

urlpatterns = patterns('',

    #...#

    (r'^inplaceeditform/', include('inplaceeditform.urls')),
    (r'^jsi18n$', 'django.views.i18n.javascript_catalog', js_info_dict),
)

Usage

Calling inplace_edit tag you can inplace edit any data from the database. It is important to clarify that the inline edition is not only for text fields, although it may be the more common usage. You can also have inline edition for choices, boolean fields, date and datetime fields, foreing keys, many to many, file and image fields.

{% inplace_edit  "OBJ.FIELD_NAME" %}
{% inplace_edit  "OBJ.FIELD_NAME|FILTER1|FILTER2|...|FILTERN" %}

Simple example

{% load inplace_edit %}
   <html>
       <head>
           ...
           <script src="{{ STATIC_URL }}js/jquery.min.js" type="text/javascript"></script>
           {% inplace_toolbar %} {% comment %} or inplace_static {% endcomment %}
       </head>
       <body>
           ...
           <div id="content">
               ...
               {% inplace_edit "content.name" %}
               ...
               <div class="description">
                   {% inplace_edit "content.date_initial|date:'d m Y'" %}
                   {% inplace_edit "content.description|safe" %}
               </div>
               <div class="body">
                   {% inplace_edit "content.body|safe|truncatewords_html:15" %}
               </div>
           </div>
           ...
       </body>
   </html>

Advanced Usage

Inplaceedit has some optionals parameters that the templatetag can receive to change its behavior:
  • auto_height: Adapt the height’s widget to the tag container.
  • auto_width: Adapt the width’s widget to the tag container.
  • min_width: The minimum of the width’s widget
  • class_inplace: Add a class to edit inline form.
  • tag_name_cover: The value is covered for a span. But it’s possible to change it.
  • filters_to_edit: The server filters the value before to save. List separate for “|”
  • loads: If you use some filter that need a load, you set this option. List separate for ”:”
  • edit_empty_value: The text to display when the field is empty

Examples

{% inplace_edit "content.description|safe" auto_height=1, auto_width=1 %}
{% inplace_edit "content.title" class_inplace="titleFormEditInline" %}
{% inplace_edit "content.description|safe|truncatewords_html:30"  tag_name_cover="div" %}
{% inplace_edit "content.description|my_filter" loads="my_template_tag" %}
{% inplace_edit "content.description|my_filter" filters_to_edit="slice:'10'|truncatewords:'2'%}
{% inplace_edit "content.index" edit_empty_value="This is a editable content, now the value is none. Please double click to edit inplace" %}
{% inplace_edit "content.amount" min_width="100" %}

Now (>=1.2.0 release) you can overwrite the generic options in the templatetag. Before this only were customizable in the settings, that is to say this options were the same to every inplace edit item:

  • getFieldUrl: “/inplaceeditform/get_field/”,
  • saveURL”: “/inplaceeditform/save/”,
  • successText, INPLACEEDIT_SUCCESS_TEXT in the settings
  • eventInplaceEdit, INPLACEEDIT_EVENT in the settings
  • disableClick, INPLACEEDIT_DISABLE_CLICK in the settings
  • autoSave, INPLACEEDIT_AUTO_SAVE in the settings
  • enableClass, INPLACE_ENABLE_CLASS in the settings
  • fieldTypes, INPLACE_FIELD_TYPES in the settings
  • focusWhenEditing, INPLACE_FOCUS_WHEN_EDITING in the settings

Only unsavedChanges (INPLACEEDIT_UNSAVED_TEXT in the settings) is a generic option.

Examples

{% inplace_edit "content.description|safe" getFieldUrl="/myapp/get_field/" %}
{% inplace_edit "content.title" autoSave="1", eventInplaceEdit="click" %}

Customizing django-inplaceedit

django-inplaceedit is generic, customizable and extensible.

Permission Adaptor API

By default you can inline edit a field if you are authenticated with a superuser. But it’s customizable:

Overwriting the default permission adaptor

This package have two inplementations:

ADAPTOR_INPLACEEDIT_EDIT = 'inplaceeditform.perms.AdminDjangoPermEditInline'

You can create a specify adaptor. MyAdaptorEditInline is a class with a single class method, this method receives a adaptor field

# in your settings

ADAPTOR_INPLACEEDIT_EDIT = 'app_name.perms.MyAdaptorEditInline'


# in app_name.perms

class MyAdaptorEditInline(object):

    @classmethod
    def can_edit(cls, adaptor_field):
       return True # All user can edit

Example

class MyAdaptorEditInline(object):

    @classmethod
    def can_edit(cls, adaptor_field):
        user = adaptor_field.request.user
        obj = adaptor_field.obj
        can_edit = False
        if user.is_anonymous():
            pass
        elif user.is_superuser:
            can_edit = True
        else:
           can_edit = has_permission(obj, user, 'edit')
        return can_edit

Creating an adaptor

You can create an adaptor to work with django-inplaceedit, the behavior is fully customizable. To default inplaceedit has 17 adaptors (AdaptorTextField, AdaptorTextAreaField, AdaptorChoicesField, AdaptorBooleanField, AdaptorDateTimeField, AdaptorForeingKeyField, AdaptorManyToManyField, AdaptorImageField etc). These use the api, overwriting some methods for them.

You can see four examples in django-inplaceedit-extra-fields project

First step

In your settings:

ADAPTOR_INPLACEEDIT = {'myadaptor': 'app_name.fields.MyAdaptor'}

In app_name.fields.MyAdaptor:

class MyAdaptor(BaseAdaptorField):

    @property
    def name(self):
        return 'myadaptor'

You can overwrite a default adaptor. To overwrite a adaptor add in your settings something like this:

ADAPTOR_INPLACEEDIT = {'text': 'app_name.fields.MyAdaptorText'}

For this case you overwrite the AdaptorText with MyAdaptorText.

Python API

  • loads_to_post: It returns the value of the request (normally request.POST)
  • classes: Classes of tag cover. By default “inplaceedit” and “myadaptorinplaceedit”
  • get_config: Preprocessed of the configuration. By default, it does nothing.
  • get_form_class: It returns the form class.
  • get_form: It returns a instace of form class.
  • get_field: It returns a field of instance of form class.
  • render_value: It returns the render of the value. If you write {% inplace_edit “obj.name|filter1” %} it returns something like this {{ obj.name|filter1 }}.
  • render_value_edit: It returns the render value if you can edit. It returns by default the same of “render_value”, but if the value is None call to empty_value
  • empty_value: It returns an empty value for this adaptor. By default, ‘Dobleclick to edit’.
  • render_field: It returns the render of form, with a field.
  • render_media_field: It returns the media (scripts and css) of the field.
  • render_config: It returns the render of config.
  • can_edit: It returns a boolean that indicate if this user can edit inline this content or not.
  • get_value_editor: It returns a clean value to be saved in DB.
  • save: Save the value in DB.
  • get_auto_height: Returned if the field rendered with auto height
  • get_auto_width: Returned if the field rendered with auto width
  • treatment_height: Special treatment to widget’s height.
  • treatment_width: Special treatment to widget’s width.
If you want to use own options in your adaptor, you can do it. These options will be in self.config in the adaptor.
{% inplace_edit "obj.field_name" my_opt1="value1", my_opt2="value2" %}

JavaScript API

You can change the javascript behaviour by adding or overriding methods from the original implementation by adding the special file jquery.inplaceeditform.hooks.js to your project. $.inplaceeditform.extend takes an object with the new or replacement methods.

$.inplaceeditform.extend(
    {
        inplaceApplySuccessShowMessage: function(inplace_span) {
            var self = $.inplaceeditform;
            if (self.opts.successText) {
                var modal = $('#inplaceedit-modal');
                var body = modal.find('div.modal-body p');
                body.html(self.opts.successText);

                setTimeout(function () {
                    modal.fadeOut(function () {
                        $(this).remove();
                    });
                }, 2000);
            }
            modal.show();
        }
    }
);

Additionally there are four hooks,

  • getValue: if the value is componing for various widgets, you can set the function getValue, to these DOM elements. Something like this:

    <script type="text/javascript">
    (function($){
        $(document).ready(function () {
            function myGetValue(form, field_id) {
                return ""Something"";
            }
            $(".applyMyAdaptor").data("getValue", myGetValue);
    });
    })(jQuery);
</script>

  • applyFinish: if you need/want to do some action after the value be saved. Something like this:

    <script type="text/javascript">
    (function($){
        $(document).ready(function () {
            function myApplyFinish(applyButton) {
                return ""Something"";
            }
            $(".applyMyAdaptor").data("applyFinish", myApplyFinish);
    });
    })(jQuery);
</script>

  • cancelFinish: if you need/want to do some action after the cancel the edit. Something like this:

    <script type="text/javascript">
    (function($){
        $(document).ready(function () {
            function myCancelFinish(cancelButton) {
                return ""Something"";
            }
            $(".cancelMyAdaptor").data("cancelFinish", myCancelFinish);
    });
    })(jQuery);
</script>

  • extraConfig: if you need/want add something to the config in the ajax request to print the field

    <script type="text/javascript">
    (function($){
        $(document).ready(function () {
            function myExtraConfig(data) {
                return data + ""Something"";
            }
            $(".configMyAdaptor").data("extraConfig", myExtraConfig);
    });
    })(jQuery);
</script>

For example the adaptor datetime use these hooks.

Testing

This django application has been tested on severals browsers: Firefox, Google Chrome, Opera, Safari and Internet Explorer on versions 7, 8, 9 and 10 to check javascript actions. Attention, jQuery 2 does not support IE 6/7/8. If you want to test in these browsers, please use jQuery 1 (recomended the last release 1.10.2)

Exists a testing django project. This project can use as demo project, because django-inplaceedit is totally adapted to it.

Also you can use the demo project of django-inplaceedit-bootstrap

The backend has unit test, to check it.:

cd testing
python run_tests.py

You can see this django-inplaceedit works (without changes) from django 1.2, and even in previous versions of Django (1.1 and 1.0) works with some customizations.

Development

You can get the last bleeding edge version of inplaceedit by doing a clone of its git repository:

git clone git://github.com/django-inplaceedit/django-inplaceedit.git