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

yuidoc comments

Browse Source
This commit is contained in:
vitalets 2012-11-12 22:04:01 +04:00
parent 348134c575
commit 8a64d3fb28
9 changed files with 464 additions and 127 deletions

18
grunt.js

@ -187,6 +187,24 @@ containers = lib+'containers/';
}
}
},
yuidoc: {
compile: {
name: '<%= pkg.title || pkg.name %>',
description: '<%= pkg.description %>',
version: '<%= pkg.version %>',
url: "<%= pkg.homepage %>",
// logo: 'src/editable-form/img/loading.gif',
options: {
paths: "src/",
ignorePaths: ['src/inputs/date/locales'],
outdir: "../docs/",
// theme: "simple",
themedir: "../yuidoc-theme"
//themedir: "../yuidoc-bootstrap-theme-master"
}
}
},
//compress does not work properly for MAC OS (see https://github.com/vitalets/bootstrap-editable/issues/19)
//zip will be created manually
/*

9
package.json

@ -1,5 +1,5 @@
{
"name": "x-editable",
"name": "X-editable",
"title": "X-editable",
"description": "In-place editing with Twitter Bootstrap, jQuery UI or pure jQuery",
"version": "1.0.0",
@ -19,10 +19,6 @@
{
"type": "MIT",
"url": "https://github.com/vitalets/x-editable/blob/master/LICENSE-MIT"
},
{
"type": "GPL",
"url": "https://github.com/vitalets/x-editable/blob/master/LICENSE-GPL"
}
],
"dependencies": {
@ -30,8 +26,7 @@
},
"devDependencies": {
"grunt": "~0.3.11",
"grunt-contrib": "0.1.1",
"moment": "1.7.0"
"grunt-contrib": "0.1.1"
},
"keywords": []
}

202
src/containers/editable-container.js

@ -1,26 +1,15 @@
/**
* Editable Container
* Container can be popover, inline form or whatever
* Container must provide following:
* 1. methods:
* show(),
* hide(),
* tip() - returns jquery object of container element
* option()
*
* 2. events:
* - save
* - cancel
*
* 3. settings: trigger, value, placement
*/
Container for editableform. It can be popup (bootstrap-popover, jqueryui-tooltip, poshytip..) or inline.
Applied as jQuery method to any element. Element is used only for positioning!
@class editableContainer
**/
(function ($) {
//Constructor
var EditableContainer = function (element, options) {
this.init(element, options);
};
//methods
EditableContainer.prototype = {
containerName: null, //tbd in child class
@ -28,18 +17,19 @@
init: function(element, options) {
this.$element = $(element);
this.options = $.extend({}, $.fn.editableContainer.defaults, $.fn.editableform.utils.getConfigData(this.$element), options);
this.options.trigger = 'manual';
this.initContainer();
//bind 'destroyed' listener to destroy container when element is removed from dom
this.$element.on('destroyed', $.proxy(function(){
this.destroy();
}, this));
},
initContainer: function(){
this.call(this.options);
this.call(this.options);
},
initForm: function() {
this.$form = $('<div>')
.editableform(this.options)
@ -52,92 +42,152 @@
return this.$form;
},
/**
Returns jquery object of container
@method tip()
**/
tip: function() {
return this.container().$tip;
return this.container().$tip;
},
//return instance of container
container: function() {
return this.$element.data(this.containerName);
return this.$element.data(this.containerName);
},
//call container's method
call: function() {
this.$element[this.containerName].apply(this.$element, arguments);
this.$element[this.containerName].apply(this.$element, arguments);
},
/**
Shows container with form
@method show()
**/
show: function () {
this.call('show');
this.tip().addClass('editable-container');
this.initForm();
this.tip().find(this.innerCss).empty().append(this.$form);
this.$form.editableform('render');
},
hide: function() {
this.call('hide');
},
setPosition: function() {
//tbd in child class
},
cancel: function() {
if(this.options.autohide) {
this.hide();
}
this.$element.triggerHandler('cancel');
},
save: function(e, params) {
if(this.options.autohide) {
this.hide();
}
this.$element.triggerHandler('save', params);
},
option: function(key, value) {
this.options[key] = value;
this.call('option', key, value);
},
destroy: function() {
this.call('destroy');
}
},
/**
Hides container with form
@method hide()
**/
hide: function() {
this.call('hide');
},
/**
Updates the position of container when content changed.
@method setPosition()
**/
setPosition: function() {
//tbd in child class
},
cancel: function() {
if(this.options.autohide) {
this.hide();
}
/**
Fired when form was cancelled by user
@event cancel
@param {Object} event event object
**/
this.$element.triggerHandler('cancel');
},
save: function(e, params) {
if(this.options.autohide) {
this.hide();
}
/**
Fired when new value was submitted
@event save
@param {Object} event event object
@param {Object} params additional params
@param {mixed} params.newValue submitted value
@param {Object} params.response ajax response
**/
this.$element.triggerHandler('save', params);
},
/**
Sets new option
@method option(key, value)
@param {string} key
@param {mixed} value
**/
option: function(key, value) {
this.options[key] = value;
this.call('option', key, value);
},
/**
Destroys the container instance
@method destroy()
**/
destroy: function() {
this.call('destroy');
}
};
//jQuery plugin definition
$.fn.editableContainer = function (option) {
var args = arguments;
return this.each(function () {
var $this = $(this),
dataKey = 'editableContainer',
data = $this.data(dataKey),
options = typeof option === 'object' && option;
dataKey = 'editableContainer',
data = $this.data(dataKey),
options = typeof option === 'object' && option;
if (!data) {
$this.data(dataKey, (data = new EditableContainer(this, options)));
}
if (typeof option === 'string') { //call method
data[option].apply(data, Array.prototype.slice.call(args, 1));
}
});
};
//store constructor
$.fn.editableContainer.Constructor = EditableContainer;
//defaults - must be redefined!
$.fn.editableContainer.defaults = {
trigger: 'manual',
value: null,
placement: 'top',
autohide: true
/**
Initial value of form input
@property value
@type mixed
@default null
**/
value: null,
/**
Placement of container relative to element. Can be top|right|bottom|left. Not used for inline container.
@property placement
@type string
@default 'top'
**/
placement: 'top',
/**
Wether to hide container on save/cancel.
@property autohide
@type boolean
@default true
**/
autohide: true
};
/*
* workaround to have 'destroyed' event to destroy popover when element is destroyed
* see http://stackoverflow.com/questions/2200494/jquery-trigger-event-when-an-element-is-removed-from-the-dom
@ -149,5 +199,5 @@
}
}
};
}(window.jQuery));

5
src/containers/editable-popover.js

@ -6,6 +6,11 @@
(function ($) {
//extend methods
/**
Container based on Bootstrap Popover
@class editableContainer (popover)
**/
$.extend($.fn.editableContainer.Constructor.prototype, {
containerName: 'popover',
innerCss: '.popover-content p',

5
src/containers/editable-tooltip.js

@ -6,6 +6,11 @@
(function ($) {
//extend methods
/**
Container based on jQuery UI Tooltip
@class editableContainer (tooltip)
**/
$.extend($.fn.editableContainer.Constructor.prototype, {
containerName: 'tooltip',
innerCss: '.ui-tooltip-content',

8
src/editable-form/editable-form-bootstrap.js

@ -1,6 +1,10 @@
/**
* Editable-form Bootstrap engine
*/
Editableform based on Twitter Bootstrap
@class editableform (bootstrap)
@module editableform
@uses editableform
**/
(function ($) {
//form template

8
src/editable-form/editable-form-jqueryui.js

@ -1,6 +1,10 @@
/**
* Editable-form jQuery UI engine
*/
Editableform based on jQuery UI
@class editableform (jqueryui)
@module editableform
@uses editableform
**/
(function ($) {
$.extend($.fn.editableform.Constructor.prototype, {

151
src/editable-form/editable-form.js

@ -1,21 +1,12 @@
/**
* Editable-form plugin
* Form with single input element, two buttons and automatic loader, shown on init/submit
* Plugin applied to DIV tag and show form inside
* Input must be one of following types:
* - text
* - textarea
* - select
* - date
* - <your input here>
*
* EVENTS:
* - render
* - resize
* - save
*/
(function ($) {
Form with single input element, two buttons and two states: normal/loading.
Applied as jQuery method to DIV tag (not to form tag!)
Editableform is linked with one of input types, e.g. 'text' or 'select'.
@class editableform
**/
(function ($) {
var EditableForm = function (element, options) {
this.options = $.extend({}, $.fn.editableform.defaults, options);
this.$container = $(element); //div, containing form
@ -42,6 +33,11 @@
initTemplate: function() {
this.$form = $($.fn.editableform.template);
},
/**
Renders editableform
@method render
**/
render: function() {
this.$loading = $(this.options.loading);
this.$container.empty().append(this.$loading);
@ -49,6 +45,11 @@
this.initTemplate();
/**
Fired when rendering starts
@event rendering
@param {Object} event event object
**/
this.$container.triggerHandler('rendering');
//render input
@ -72,6 +73,11 @@
}, this));
},
cancel: function() {
/**
Fired when form was cancelled by user
@event cancel
@param {Object} event event object
**/
this.$container.triggerHandler('cancel');
},
showLoading: function() {
@ -96,7 +102,12 @@
showForm: function() {
this.$loading.hide();
this.$form.show();
this.input.activate();
this.input.activate();
/**
Fired when form is shown
@event show
@param {Object} event event object
**/
this.$container.triggerHandler('show');
},
@ -145,6 +156,19 @@
.done($.proxy(function(response) {
this.error(false);
this.value = newValue;
/**
Fired when form is submitted
@event save
@param {Object} event event object
@param {Object} params additional params
@param {mixed} params.newValue submitted value
@param {Object} params.response ajax response
@example
$('#form-div').on('save'), function(e, params){
if(params.newValue === 'username') {...}
});
**/
this.$container.triggerHandler('save', {newValue: newValue, response: response});
}, this))
.fail($.proxy(function(xhr) {
@ -194,7 +218,22 @@
}
};
//jquery plugin definition
/*
Initialize editableform. Applied to jQuery object.
@method $().editableform(options)
@params {Object} options
@example
var $form = $('&lt;div&gt;').editableform({
type: 'text',
name: 'username',
url: 'post.php',
value: 'vitaliy'
});
//to display form you should call 'render' method
$form.editableform('render');
*/
$.fn.editableform = function (option) {
var args = arguments;
return this.each(function () {
@ -217,14 +256,86 @@
//defaults
$.fn.editableform.defaults = {
/* see also defaults for input */
/**
Type of input. Can be text|textarea|select|date
@property type
@type String
@default 'text'
**/
type: 'text',
/**
Url for submit
@property url
@type String|Object|Array
@default null
**/
url:null,
/**
Additional params for submit
@property params
@type Object
@default null
**/
params:null,
/**
Name of field. Will be submitted on server. Can be taken from id attribute.
@property name
@type String
@default null
**/
name: null,
/**
Primary key of editable object (e.g. record id in database). Use Object for composite keys.
@property pk
@type String|Object|Function
@default null
**/
pk: null,
value: null, //initial value
send: 'auto', //always|auto|never
/**
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).
@property value
@type String|Object
@default null
**/
value: null,
/**
Strategy for sending data on server. Can be auto|always|never.
When 'auto' data will be sent on server only if pk defined, otherwise new value will be stored in element.
@property send
@type String
@default 'auto'
**/
send: 'auto',
/**
Template for loading element
@property loading
@type String
@default <div class="editableform-loading"></div>
**/
loading: '<div class="editableform-loading"></div>',
/**
Function for client-side validation. If returns string - means validation not passed and string showed as error.
@property validate
@type Function
@default null
@example
validate: function(value) {
if($.trim(value) == '') {
return 'This field is required';
}
}
**/
validate: null
};

185
src/element/editable-element.js

@ -1,11 +1,9 @@
/**
* Editable-element
* Initialize HTML element that can be editable by click.
* 1. methods
*
* 2. events
* - render
*/
Makes editable any HTML element on page.
Applied as jquery method.
@class editable
**/
(function ($) {
var Editable = function (element, options) {
@ -27,7 +25,7 @@
//editableContainer must be defined
if(!$.fn.editableContainer) {
$.error('You must define $.fn.editableContainer via including corresponding file (e.g. editablePopover)');
$.error('You must define $.fn.editableContainer via including corresponding file (e.g. editable-popover.js)');
return;
}
@ -89,11 +87,28 @@
} else {
this.enable();
}
/**
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.
@event render
@param {Object} event event object
@param {Object} editable editable instance
@example
$('#action').on('render', function(e, editable) {
var colors = {0: "gray", 1: "green", 2: "blue", 3: "red"};
$(this).css("color", colors[editable.value]);
});
**/
this.$element.triggerHandler('render', this);
this.isInit = false;
}, this));
},
/**
Enables editable
@method enable()
**/
enable: function() {
this.options.disabled = false;
this.$element.removeClass('editable-disabled');
@ -106,6 +121,10 @@
}
},
/**
Disables editable
@method disable()
**/
disable: function() {
this.options.disabled = true;
this.hide();
@ -117,6 +136,10 @@
}
},
/**
Toggles enabled / disabled state of editable element
@method toggleDisabled()
**/
toggleDisabled: function() {
if(this.options.disabled) {
this.enable();
@ -125,6 +148,13 @@
}
},
/**
Sets new option
@method option(key, value)
@param {string} key
@param {mixed} value
**/
option: function(key, value) {
if(key === 'disabled') {
if(value) {
@ -143,7 +173,7 @@
}
},
/**
/*
* set emptytext if element is empty (reverse: remove emptytext if needed)
*/
handleEmpty: function () {
@ -175,8 +205,9 @@
},
/**
* show container with form
*/
Shows container with form
@method show()
**/
show: function () {
if(this.options.disabled) {
return;
@ -206,8 +237,9 @@
},
/**
* hide container with form
*/
Hides container with form
@method hide()
**/
hide: function () {
if(this.container && this.container.tip().is(':visible')) {
this.container.hide();
@ -220,8 +252,9 @@
},
/**
* show/hide form container
*/
Toggles container visibility (show / hide)
@method toggle()
**/
toggle: function () {
if(this.container && this.container.tip().is(':visible')) {
this.hide();
@ -230,7 +263,7 @@
}
},
/**
/*
* called when form was submitted
*/
save: function(e, params) {
@ -261,6 +294,12 @@
}
},
/**
Sets new value of editable
@method setValue(v, convertStr)
@param {mixed} v new value
@param {boolean} convertStr wether to convert value from string to internal format
**/
setValue: function(v, convertStr) {
if(convertStr) {
this.value = this.input.str2value(v);
@ -281,10 +320,35 @@
/* EDITABLE PLUGIN DEFINITION
* ======================= */
/**
jQuery method to initialize editable element.
@method $().editable(options)
@params {Object} options
@example
$('#username').editable({
type: 'text',
url: 'post.php',
pk: 1
});
**/
$.fn.editable = function (option) {
//special methods returning non-jquery object
//special API methods returning non-jquery object
var result = {}, args = arguments, datakey = 'editable';
switch (option) {
/**
Runs client-side validation for all editables in jquery array
@method validate()
@returns {Object} validation errors map
@example
$('#username, #fullname').editable('validate');
// possible result:
{
username: "username is requied",
fullname: "fullname should be minimum 3 letters length"
}
**/
case 'validate':
this.each(function () {
var $this = $(this), data = $this.data(datakey), error;
@ -294,6 +358,18 @@
});
return result;
/**
Returns current values of editable elements. If value is <code>null</code> or <code>undefined</code> it will not be returned
@method getValue()
@returns {Object} object of element names and values
@example
$('#username, #fullname').editable('validate');
// possible result:
{
username: "superuser",
fullname: "John"
}
**/
case 'getValue':
this.each(function () {
var $this = $(this), data = $this.data(datakey);
@ -303,6 +379,18 @@
});
return result;
/**
This method collects values from several editable elements and submit them all to server.
It is designed mainly for creating new records.
@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
@returns {Object} jQuery object
**/
case 'submit': //collects value, validate and submit to server for creating new record
var config = arguments[1] || {},
$elems = this,
@ -360,14 +448,71 @@
$.fn.editable.defaults = {
type:'text',
/**
Type of input. Can be text|textarea|select|date
@property type
@type String
@default 'text'
**/
type: 'text',
/**
Sets disabled state of editable
@property disabled
@type boolean
@default false
**/
disabled: false,
/**
How to toggle editable. Can be click|manual.
@property toggle
@type string
@default 'click'
**/
toggle: 'click',
trigger: 'manual',
/**
Text shown when element is empty.
@property emptytext
@type string
@default 'Empty'
**/
emptytext: 'Empty',
/**
Allows to automatically set element's text based on it's value. Usefull for select and date.
For example, if element's list is <code>{1: 'a', 2: 'b'}</code> value set to <code>1</code>, it's text 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.
@property autotext
@type string
@default 'auto'
**/
autotext: 'auto',
/**
Wether to return focus on element after form is closed.
This allows fully keyboard input.
@property enablefocus
@type boolean
@default false
**/
enablefocus: false,
success: function(response, newValue) {} //value successfully sent on server and response status = 200
/**
Success callback. Called when value successfully sent on server and response status = 200.
Can be used to process json response. If this function returns string - means error occured and string is shown as error message.
@property success
@type function
@default null
@example
success: function(response, newValue) {
if(!response.success) return response.msg;
}
**/
success: function(response, newValue) {}
};
}(window.jQuery));