Documentation for jinplace

Introduction

Jinplace is a jQuery plugin that is used to make sections of text on a page editable directly from the page. Editing starts by clicking on the text. It then turns into an input field where the new text can be typed. Clicking outside the field will submit the new new text and once a reply has been received, the input field is removed and the new text replaces it.

That is the basic flow, but there are a number of options to change this. So for example you can have explicit OK and cancel buttons and a separate button to start editing.

For recent changes see the news

Index

  • Complete list of attributes All the attributes and configuration settings and how to use them.
  • Sending and receiving data About supplying data to the editing controls and sending it to the server.
  • Events The events that are triggered. They can be used to add your own actions to be performed on success or failure of the editing operation.
  • Writing an editor plugin A complete walkthrough of developing a new editor plugin.
  • The demo has code examples and their result.

Basic usage

Include the javascript files

As this is a jQuery plugin, you must include a version of jQuery first. It will work with jQuery greater than or equal to version 1.7. If you use version 2.0 or above, then you will of course lose IE6-8 compatibility.

Add the following line to include the plugin from the cdnjs.com delivery network.

 <script src="//cdnjs.cloudflare.com/ajax/libs/jinplace/1.2.1/jinplace.min.js"></script>

Or you can download the latest version of this plugin from the download directory and include it in your project.

Mark up the page

You should read this section in conjunction with the demo which is structured like a mini tutorial for some of the basic mark up attributes.

If text that you want to edit is already contained within an HTML element then you can just add a class and the jinplace attributes to it. If not, or you just wish to keep things separate, then just surround the text with a 'span' or 'div' element as appropriate.

Title: <span class="editable" data-url="/update_title.php">Hello world</span>

References

First read through the demo which includes the exact code samples required for various features.

Then for complete details

Sending and receiving data

This section answers the question: What is sent to the server?

Sending the modified value

when editing has finished, the new value is sent to the server using an ajax call.

The new value is sent as a parameter named 'value' using POST to the url specified. There may be additional parameters sent as follows.

  • If the element has an id then it will be sent with parameter name 'id'.
  • If 'data-attribute' is set (or the config setting 'attribute' is present) then its value is sent under the parameter name 'attribute'.
  • If 'data-object' is set (or the 'object' setting), then its value is sent under the parameter name 'object'.

The returned value is used to set the text within the editable element and replace the editing control. So if the editing format and the display format differ, then it is the display format that is returned.

For example, for a select dropdown, it will be the text of the selected option.

Loading data

When 'data-loadurl' is used, then a GET call is made to the server with exactly the same parameters as in the previous section, except that there is no 'value' parameter to send.

The value returned is used to initialise the editing field, and so it must be in its editing format if that differs from the display format.

Data formats for each input type

input

Takes text and so there is normally nothing special to do, the editing and display formats are the same.

An exception might be is cases such as when the data is held in markdown or a variety of wiki text. In this case you might want to edit the wiki text, but display html. So on saving the changed wiki text, the server will format to html and return that as the display text. To display html as formatted areas, rather than literal html (with the angle brackets) you need to set textOnly to false.

textarea

This is exactly the same considerations as for 'input'.

select

The display format is the text of the selected option. However the editing format is a json list of all the possible options so that a dropdown can be constructed.

The option list is formatted as in this example

[["1", "Red"], ["2", "Green", 1], ["3", "Blue"]]

Above there are three options 1, 2 and 3, with the values 'Red',' Green' and 'Blue'. The value 2/Green is currently selected.

If none of the options are marked as selected then it will attempt to work it out by looking at the existing text in the element.

When a selection is made to say, Blue, then the value '3' will be posted to the server, and the display value 'Blue' will be returned in the normal case.

HTML data attributes

All fields on a page that you want to be editable can be marked up using HTML data-* attributes. The plugin uses these to set up the element so that it can be edited on the page and the value submitted to the server.

The simplest case would look something like this

 <span class="editable" data-url="/api/modify/188/name">Zoe</span>

HTML data attributes

Here we have the complete list of data attributes that can be set.

data-url

The url to submit the form data to. The default is the same url as the page itself. It must be a page that can accept submitted form data.

 <span class="editable" data-url="/api/modify/188/name">Jo</span>

data-type

The type of form element to be created. Can be one of 'input' for a regular text input, 'select' for a select dropdown box, or 'textarea' for a multiline text area. The default is 'input'.

 <div class="editable" data-url="/api/modify/188/bio"
   data-type="textarea" >
   This could be a long section of text.
 </div>

data-activator

This is a selector for an element which should be used to activate the edit area rather than clicking on the text itself. Usually you would use an id to uniquely identify the edit button.

 <div class="editable" data-url="/api/modify/188/bio"
   data-type="textarea"
   data-activator="#bio-edit">
   This could be a long section of text.
 </div>
 <span id="bio-edit" class="button">Edit!</span>

In this example clicking on the word 'Edit!' will activate the editing control.

data-data

If supplied this is the editable version of the text. In the case of a select edit control, it must be a JSON list of value, text pairs. If neither data-data nor data-loadurl is supplied, then the editing control is initialised with the text from the element.

 <span class="editable" data-url="/api/modify/188/colour"
   data-data='[["1", "Red"], ["2", "Green"], ["3", "Blue"]]'>Blue</span>

data-loadurl

If set then it is the url from which to load data. A GET http request is made to the 'loadurl' with the same parameters that would be sent on submit. The server returns data that is used as the initial value of the edit field.

In the example, the dropdown list is supplied by the server.

 <span class="editable" data-url="/api/modify/188/colour"
   data-loadurl='/api/lists/colours'>Blue</span>

This is useful if the text is in markdown, textile or other wiki like format. The loadurl fetches the wiki text which is edited and sent to the server to update. The server then returns the HTML version of the field to display.

data-ok-button

If set, then there will be an OK button next to the input or textarea field. The text on the button will be the value of this option. By default there is no submit button, and data is submitted on blur. If there is only an OK button, then blur cancels the edit without submitting anything to the server.

 <span class="editable" data-url="/api/modify/188/name"
   data-ok-button='OK'>Jim</span>

Buttons can only be associated with text inputs, ie 'input' and' textarea'.

data-cancel-button

If set, then there will be a cancel button next to the input or textarea field. The text on the button will be the value of this option. By default there is no cancel button. If there are both OK and cancel buttons, then blur has no effect and you must either explicitly click OK or cancel. This is in my opinion the best option for large text fields.

 <div class="editable" data-url="/api/modify/188/bio"
   data-ok-button='OK'
   data-cancel-button='Cancel'>
  Lots of text here.
 </div>

data-attribute

If set then this value will be sent to the server as part of the post data. It is intended to identify the field of a particular object that is being set, but you can of course use it however you like.

data-object

If set the this value will be sent to the server as part of the post data. It is intended to identify the object to be set, but you can interpret it in any way that you like.

 <span class="editable" data-url="/api/modify"
   data-ok-button='OK'
   data-cancel-button='Cancel'
   data-object="188"
   data-attribute="name">
  Pete
 </span>

data-text-only

If set (which is the default) then data is displayed as text. That is to say '<p>' would display literally and does not cause a paragraph break. If you disable it then the data received back from the server will be interpreted as html. You are responsible for making sure this is safe.

data-placeholder

If the element is empty, then you would not be able to click on it to start editing. So if it is empty, then jinplace will add the placeholder text as specified with this attribute or config setting. When editing, this placeholder text is removed. The default value is '[ --- ]' (This attribute was named 'data-nil' in previous versions)

data-input-class

The input field will have this class. There is no default.

Config settings

You can use any of the data attributes as a config setting when you call .jinplace(). The setting name is formed by removing the 'data-' prefix and changing hyphenated words with camel case words. So ' data-attribute' is 'attribute' and 'data-text-only' is 'textOnly'.

An object can be passed to .jinplace() containing the desired settings.

$('editable').jinplace({
   url: '/api/modify',
   textOnly: false,
   placeholder: 'Click to edit',
   okButton: 'OK',
   cancelButton: 'Cancel'
});

You can also set defaults that will apply to all .jinplace() calls.

$.fn.jinplace.defaults.textOnly = false;

Some settings can only be set this way and not via attributes of the element you want to edit. These are listed in the remainder of this section.

submitFunction

This is the function that is called to submit the new data. The function is called with two arguments, first the jinplace options for the element and second the new value. It should return the new value as a string or a promise that resolves to a string.

This value will be used to replace the original element text. Inside the function, 'this' should be considered to be undefined (it will be window for a non-strict mode function).

// Minimum example that does nothing.
$('.editable').jinplace({
   submitFunction: function(opts, value) {
       return value;
   }
   });

If the function returns undefined, then the edit is cancelled and the element content returns to its original state.

You can also return a 'promise' from the function. This is useful if for example you want to make a different kind of ajax call than the default one. The promise should resolve to a string value.

// This is roughly what the default processing of submit does.
$('.editable').jinplace({
   submitFunction: function(opts, value) {
       return $.ajax(opts.url, {
                   type: "post",
                   data: {
                       item: opts.attribute, object: opts.object,
                       id: opts.elementId, value: value
                   },
                   dataType: 'text',
               });
   }
   });

loadFunction

This is the function that is called when editing data is fetched from the remote server. It is called with a single argument which is the jinplace options for the element.

Note that you have to have a data-loadurl (or the loadurl setting) for this function to be called. So a dummy one must be supplied if you have no actual use for it.

The default function is roughly as follows.

$.fn.jinplace.defaults.loadFunction = function(opts) {
   return $.ajax(opts.loadurl, {
       data: {
           id: opts.elementId,
           object: opts.object
           attribute: opts.attribute,
       }
   });
}

Events

General example

Here is a quick example of how to bind the event that is sent after a successful edit. This is just standard use of the jquery .on() method, so see the jquery documentation for more information.

// Bind to the 'jinplace:done' event on all editable elements and
// print a message.  Of course you can bind to individual elements
// as you require.
$('.editable').jinplace()
   .on('jinplace:done', function(ev, data) {
       console.log('Successful edit! New value is', data);
   });

Available events

Full details of all the available events. These events are always fired, even if you define your own submitFunction. Either 'jinplace:done' or 'jinplace:fail' will be fired, followed by 'jinplace:always'.

Event jinplace:done

This event is fired after a submit is successfully completed. It occurs after the submit operation and before the edit field is taken down and the original text returned.

element.on('jinplace:done',
   // ev: The event object itself
   // data: The new text for the element
   // textStatus: Text from the http reply.
   // jqxhr: the jquery version of the XmlHttpRequest object
   function(ev, data, [textStatus, [jqxhr]]) {
   }
);

Your handler function is always passed the following arguments.

ev : The event object

data : The data returned by the submit which will be used to populate the text control.

By default, unless you supply a submitFunction, there will be two further arguments from the ajax call.

textStatus : A text representation of the http status, normally blank

jqxhr : The jquery enhanced XmlHttpRequest object.

If a custom 'submitFunction' is defined then the arguments (if any) are entirely determined by that function.

Event jinplace:fail

This event is fired after a submit fails. It occurs after the submit operation and before the edit field is taken down.

There will never be both a jinplace:done and a jinplace:fail for the same submit operation.

element.on('jinplace:fail',
   // ev: The event object itself
   // jqxhr: the jquery version of the XmlHttpRequest object
   // textStatus: Text status: "error", "timeout" etc
   // errorThrown: The text in the error reply
   function(ev, jqxhr, textStatus, errorThrown) {
   }
);

If you have not overridden the 'submitFunction' then the handler will be passed the following arguments from the ajax call.

ev : The event object, this is always passed.

jqxhr : The jquery enhanced XmlHttpRequest object.

textStatus : This will be 'error', 'timeout', 'parsererror', 'abort' etc to describe the kind of error.

errorThrown : This is the text part of the http reply such as 'Not Found'' Internal Server Error' etc. Together you may be able to use this to work out what has gone wrong and the likelihood of the user being able to correct the problem. Mostly just knowing that the operation failed is all you will need.

If a custom 'submitFunction' is defined then that function determines what arguments your handler is called with.

Event jinplace:always

This event is fired after the editing operation, no matter if it succeeds or fails. The callback functions are called after any success or fail callback functions have been run.

The arguments that the handler function receives are the same ones that the appropriate success or fail handler receives.


If a custom 'submitFunction' is defined then this event will still always be called, but the arguments that the callback functions are supplied with will depend on the submitFunction.



Created with the Personal Edition of HelpNDoc: Easily create EPub books