tracer/x-editable
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

comments for docs

Browse Source
This commit is contained in:
vitalets 2012-11-15 22:29:56 +04:00
parent 2b9b6e7bd5
commit fc7095d6ee
10 changed files with 183 additions and 53 deletions

2
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"

35
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 () {

8
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

44
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

4
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',
/**

71
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
}
});

26
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

23
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));
}(window.jQuery));

10
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) {

13
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',
/**