diff --git a/package.json b/package.json
index 208fffd..f6da3bd 100644
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
"title": "X-editable",
"description": "In-place editing with Twitter Bootstrap, jQuery UI or pure jQuery",
"version": "1.0.0",
- "homepage": "https://github.com/vitalets/x-editable",
+ "homepage": "http://github.com/vitalets/x-editable",
"author": {
"name": "Vitaliy Potapov",
"email": "noginsk@rambler.ru"
diff --git a/src/containers/editable-container.js b/src/containers/editable-container.js
index 7bb017b..784e07d 100644
--- a/src/containers/editable-container.js
+++ b/src/containers/editable-container.js
@@ -45,10 +45,10 @@ Applied as jQuery method.
return this.$form;
},
- /**
+ /*
Returns jquery object of container
@method tip()
- **/
+ */
tip: function() {
return this.container().$tip;
},
@@ -82,10 +82,10 @@ Applied as jQuery method.
this.call('hide');
},
- /**
+ /*
Updates the position of container when content changed.
@method setPosition()
- **/
+ */
setPosition: function() {
//tbd in child class
},
@@ -113,8 +113,17 @@ Applied as jQuery method.
@event save
@param {Object} event event object
@param {Object} params additional params
- @param {mixed} params.newValue submitted value
- @param {Object} params.response ajax response
+ @param {mixed} params.newValue submitted value
+ @param {Object} params.response ajax response
+ @example
+ $('#username').on('save', function(e, params) {
+ //assuming server response: '{success: true}'
+ if(params.response && params.response.success) {
+ alert('value ' + params.newValue + ' saved!');
+ } else {
+ alert('error!');
+ }
+ });
**/
this.$element.triggerHandler('save', params);
},
@@ -141,7 +150,19 @@ Applied as jQuery method.
};
- //jQuery plugin definition
+ /**
+ jQuery method to initialize editableContainer.
+
+ @method $().editableContainer(options)
+ @params {Object} options
+ @example
+ $('#edit').editableContainer({
+ type: 'text',
+ url: 'post.php',
+ pk: 1,
+ value: 'hello'
+ });
+ **/
$.fn.editableContainer = function (option) {
var args = arguments;
return this.each(function () {
diff --git a/src/editable-form/editable-form.js b/src/editable-form/editable-form.js
index 8be2e92..172581c 100644
--- a/src/editable-form/editable-form.js
+++ b/src/editable-form/editable-form.js
@@ -271,7 +271,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
Url for submit
@property url
- @type string|object|array
+ @type string|function
@default null
**/
url:null,
@@ -284,7 +284,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
**/
params:null,
/**
- Name of field. Will be submitted on server. Can be taken from id attribute.
+ Name of field. Will be submitted on server. Can be taken from <code>id</code> attribute
@property name
@type string
@@ -301,7 +301,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
pk: null,
/**
Initial value. If not defined - will be taken from element's content.
- For <i>select</i> type should be defined (as it is ID of shown text).
+ For __select__ type should be defined (as it is ID of shown text).
@property value
@type string|object
@@ -309,7 +309,7 @@ Editableform is linked with one of input types, e.g. 'text' or 'select'.
**/
value: null,
/**
- Strategy for sending data on server. Can be auto|always|never.
+ Strategy for sending data on server. Can be <code>auto|always|never</code>.
When 'auto' data will be sent on server only if pk defined, otherwise new value will be stored in element.
@property send
diff --git a/src/element/editable-element.js b/src/element/editable-element.js
index 9defd03..6317ff3 100644
--- a/src/element/editable-element.js
+++ b/src/element/editable-element.js
@@ -89,7 +89,7 @@ Makes editable any HTML element on the page. Applied as jQuery method.
}
/**
Fired each time when element's text is rendered. Occurs on initialization and on each update of value.
- Can be used for customizing display of value.
+ Can be used for display customization.
@event render
@param {Object} event event object
@@ -296,15 +296,15 @@ Makes editable any HTML element on the page. Applied as jQuery method.
/**
Sets new value of editable
- @method setValue(v, convertStr)
- @param {mixed} v new value
+ @method setValue(value, convertStr)
+ @param {mixed} value new value
@param {boolean} convertStr wether to convert value from string to internal format
**/
- setValue: function(v, convertStr) {
+ setValue: function(value, convertStr) {
if(convertStr) {
- this.value = this.input.str2value(v);
+ this.value = this.input.str2value(value);
} else {
- this.value = v;
+ this.value = value;
}
if(this.container) {
this.container.option('value', this.value);
@@ -337,7 +337,7 @@ Makes editable any HTML element on the page. Applied as jQuery method.
var result = {}, args = arguments, datakey = 'editable';
switch (option) {
/**
- Runs client-side validation for all editables in jquery array
+ Runs client-side validation for all matched editables
@method validate()
@returns {Object} validation errors map
@@ -345,8 +345,8 @@ Makes editable any HTML element on the page. Applied as jQuery method.
$('#username, #fullname').editable('validate');
// possible result:
{
- username: "username is requied",
- fullname: "fullname should be minimum 3 letters length"
+ username: "username is requied",
+ fullname: "fullname should be minimum 3 letters length"
}
**/
case 'validate':
@@ -381,14 +381,14 @@ Makes editable any HTML element on the page. Applied as jQuery method.
/**
This method collects values from several editable elements and submit them all to server.
- It is designed mainly for creating new records.
+ It is designed mainly for <a href="#newrecord">creating new records</a>.
@method submit(options)
@param {object} options
@param {object} options.url url to submit data
@param {object} options.data additional data to submit
- @param {function} options.error error handler (called on both client-side and server-side validation errors)
- @param {function} options.success success handler
+ @param {function} options.error(obj) error handler (called on both client-side and server-side validation errors)
+ @param {function} options.success(obj) success handler
@returns {Object} jQuery object
**/
case 'submit': //collects value, validate and submit to server for creating new record
@@ -452,7 +452,7 @@ Makes editable any HTML element on the page. Applied as jQuery method.
Type of input. Can be <code>text|textarea|select|date</code>
@property type
- @type String
+ @type string
@default 'text'
**/
type: 'text',
@@ -465,7 +465,15 @@ Makes editable any HTML element on the page. Applied as jQuery method.
**/
disabled: false,
/**
- How to toggle editable. Can be click|manual.
+ How to toggle editable. Can be <code>click|manual</code>.
+ When set to <code>manual</code> you should manually call <code>show/hide</code> methods of editable.
+ Note: if you are calling <code>show</code> on **click** event you need to apply <code>e.stopPropagation()</code> because container has behavior to hide on any click outside.
+
+ @example
+ $('#edit-button').click(function(e) {
+ e.stopPropagation();
+ $('#username').editable('toggle');
+ });
@property toggle
@type string
@@ -481,10 +489,10 @@ Makes editable any HTML element on the page. Applied as jQuery method.
**/
emptytext: 'Empty',
/**
- Allows to automatically set element's text based on it's value. Usefull for select and date.
- For example, if dropdown list is <code>{1: 'a', 2: 'b'}</code> and elements value set to <code>1</code>, it's html will be automatically set to <code>a</code>.
- Can be auto|always|never. <code>auto</code> means text will be set only if element is empty.
- <code>always|never</code> means always(never) try to set element's text.
+ Allows to automatically set element's text based on it's value. Can be <code>auto|always|never</code>. Usefull for select and date.
+ For example, if dropdown list is <code>{1: 'a', 2: 'b'}</code> and element's value set to <code>1</code>, it's html will be automatically set to <code>'a'</code>.
+ <code>auto</code> - text will be automatically set only if element is empty.
+ <code>always|never</code> - always(never) try to set element's text.
@property autotext
@type string
diff --git a/src/inputs/abstract.js b/src/inputs/abstract.js
index 9acc473..b0320cd 100644
--- a/src/inputs/abstract.js
+++ b/src/inputs/abstract.js
@@ -115,7 +115,7 @@ To create your own input you should inherit from this class.
Abstract.defaults = {
/**
- HTML template of input
+ HTML template of input. Normally you should not change it.
@property tpl
@type string
@@ -127,7 +127,7 @@ To create your own input you should inherit from this class.
@property inputclass
@type string
- @default 'span2'
+ @default span2
**/
inputclass: 'span2',
/**
diff --git a/src/inputs/date/date.js b/src/inputs/date/date.js
index 4a71848..59052dc 100644
--- a/src/inputs/date/date.js
+++ b/src/inputs/date/date.js
@@ -1,7 +1,25 @@
/**
-* date
-* based on fork: https://github.com/vitalets/bootstrap-datepicker
-*/
+Bootstrap-datepicker.
+Description and examples: http://vitalets.github.com/bootstrap-datepicker.
+For localization you can include js file from here: https://github.com/eternicode/bootstrap-datepicker/tree/master/js/locales
+
+@class date
+@extends abstract
+@example
+<a href="#" id="dob" data-type="date" data-pk="1" data-url="post.php" data-original-title="Select date">15/05/1984</a>
+<script>
+$(function(){
+ $('#dob').editable({
+ format: 'yyyy-mm-dd',
+ viewformat: 'dd/mm/yyyy',
+ datepicker: {
+ weekStart: 1
+ }
+ }
+ });
+});
+</script>
+**/
(function ($) {
var Date = function (options) {
@@ -68,15 +86,50 @@
});
Date.defaults = $.extend({}, $.fn.editableform.types.abstract.defaults, {
+ /**
+ @property tpl
+ @default <div style="float: left; padding: 0; margin: 0 0 9px 0"></div>
+ **/
tpl:'<div style="float: left; padding: 0; margin: 0 0 9px 0"></div>',
+ /**
+ @property inputclass
+ @default well
+ **/
inputclass: 'well',
- format:'yyyy-mm-dd', //format used for sending to server and converting from value
- viewformat: null, //used for display date in element
- //special options
- weekStart: 0,
- startView: 0,
+ /**
+ Format used for sending value to server. Also applied when converting date from <code>data-value</code> attribute.<br>
+ Possible tokens are: <code>d, dd, m, mm, yy, yyyy</code>
+
+ @property format
+ @type string
+ @default yyyy-mm-dd
+ **/
+ format:'yyyy-mm-dd',
+ /**
+ Format used for displaying date. Also applied when converting date from element's text on init.
+ If not specified equals to <code>format</code>
+
+ @property viewformat
+ @type string
+ @default null
+ **/
+ viewformat: null,
+ /**
+ Configuration of datepicker.
+ Full list of options: http://vitalets.github.com/bootstrap-datepicker
+
+ @property datepicker
+ @type object
+ @default {
+ weekStart: 0,
+ startView: 0,
+ autoclose: false
+ }
+ **/
datepicker:{
- autoclose:false
+ weekStart: 0,
+ startView: 0,
+ autoclose: false
}
});
diff --git a/src/inputs/dateui/dateui.js b/src/inputs/dateui/dateui.js
index 16379f7..35817d2 100644
--- a/src/inputs/dateui/dateui.js
+++ b/src/inputs/dateui/dateui.js
@@ -1,9 +1,24 @@
/**
-jQuery UI Datepicker
-Note: you can not use both date and dateui on the same page.
+jQuery UI Datepicker.
+Description and examples: http://jqueryui.com/datepicker.
+Do not use it together with bootstrap-datepicker.
@class dateui
@extends abstract
+@example
+<a href="#" id="dob" data-type="date" data-pk="1" data-url="post.php" data-original-title="Select date">15/05/1984</a>
+<script>
+$(function(){
+ $('#dob').editable({
+ format: 'yyyy-mm-dd',
+ viewformat: 'dd/mm/yyyy',
+ datepicker: {
+ firstDay: 1
+ }
+ }
+ });
+});
+</script>
**/
(function ($) {
@@ -101,7 +116,7 @@ Note: you can not use both date and dateui on the same page.
inputclass: '',
/**
Format used for sending value to server. Also applied when converting date from <code>data-value</code> attribute.<br>
- Full <a href="http://docs.jquery.com/UI/Datepicker/formatDate">list of tokens</a>.
+ Full list of tokens: http://docs.jquery.com/UI/Datepicker/formatDate
@property format
@type string
@@ -109,7 +124,8 @@ Note: you can not use both date and dateui on the same page.
**/
format:'yyyy-mm-dd',
/**
- Format used for displaying date. If not specified equals to <code>format</code>
+ Format used for displaying date. Also applied when converting date from element's text on init.
+ If not specified equals to <code>format</code>
@property viewformat
@type string
@@ -119,7 +135,7 @@ Note: you can not use both date and dateui on the same page.
/**
Configuration of datepicker.
- Full list of <a href="http://api.jqueryui.com/datepicker">possible options</a>.
+ Full list of options: http://api.jqueryui.com/datepicker
@property datepicker
@type object
diff --git a/src/inputs/select.js b/src/inputs/select.js
index 8ce39fd..2dbee93 100644
--- a/src/inputs/select.js
+++ b/src/inputs/select.js
@@ -1,8 +1,23 @@
/**
-Select input
+Select (dropdown) input
@class select
@extends abstract
+@example
+<a href="#" id="status" data-type="select" data-pk="1" data-url="post.php" data-original-title="Select status"></a>
+<script>
+$(function(){
+ $('#status').editable({
+ value: 2,
+ source: [
+ {value: 1, text: 'Active'},
+ {value: 2, text: 'Blocked'},
+ {value: 3, text: 'Deleted'}
+ ]
+ }
+ });
+});
+</script>
**/
(function ($) {
@@ -31,7 +46,7 @@ Select input
},
html2value: function (html) {
- return null; //it's not good idea to set value by text for SELECT. better set NULL
+ return null; //it's not good idea to set value by text for SELECT. Better set NULL
},
value2html: function (value, element) {
@@ -229,8 +244,6 @@ Select input
@property source
@type string|array|object
@default null
- @example
- source: 'groups.php'
**/
source:null,
/**
@@ -253,4 +266,4 @@ Select input
$.fn.editableform.types.select = Select;
-}(window.jQuery));
\ No newline at end of file
+}(window.jQuery));
diff --git a/src/inputs/text.js b/src/inputs/text.js
index 7d60ea6..3083b73 100644
--- a/src/inputs/text.js
+++ b/src/inputs/text.js
@@ -3,6 +3,16 @@ Text input
@class text
@extends abstract
+@example
+<a href="#" id="username" data-type="text" data-pk="1">awesome</a>
+<script>
+$(function(){
+ $('#username').editable({
+ url: 'post.php',
+ title: 'Enter username'
+ });
+});
+</script>
**/
(function ($) {
var Text = function (options) {
diff --git a/src/inputs/textarea.js b/src/inputs/textarea.js
index f613b74..7d9026f 100644
--- a/src/inputs/textarea.js
+++ b/src/inputs/textarea.js
@@ -3,7 +3,16 @@ Textarea input
@class textarea
@extends abstract
-@module inputs
+@example
+<a href="#" id="comments" data-type="textarea" data-pk="1">awesome comment!</a>
+<script>
+$(function(){
+ $('#comments').editable({
+ url: 'post.php',
+ title: 'Enter comments'
+ });
+});
+</script>
**/
(function ($) {
@@ -64,7 +73,7 @@ Textarea input
tpl:'<textarea rows="8"></textarea>',
/**
@property inputclass
- @default 'span3'
+ @default span3
**/
inputclass:'span3',
/**