From 880e4665c3d87570188ba831cd14ec9475980fb7 Mon Sep 17 00:00:00 2001 From: ninadsp Date: Wed, 11 Aug 2010 00:28:28 +0530 Subject: [PATCH] Added JSDoc-Toolkit compatible documentation to js/sql.js --- js/sql.js | 185 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 163 insertions(+), 22 deletions(-) diff --git a/js/sql.js b/js/sql.js index 1684b3019..2a3250aff 100644 --- a/js/sql.js +++ b/js/sql.js @@ -1,6 +1,9 @@ /* vim: set expandtab sw=4 ts=4 sts=4: */ /** - * function used wherever an sql query form is used + * @fileoverview functions used wherever an sql query form is used + * + * @requires jQuery + * @requires js/functions.js * * @version $Id$ */ @@ -75,6 +78,16 @@ function appendInlineAnchor(disp_mode) { } } +/** + * Ajax scripts for sql and browse pages + * + * Actions ajaxified here: + * Retrieve results of an SQL query + * Paginate the results table + * Sort the results table + * Change table according to display options + * Inline editing of data + */ $(document).ready(function() { /** @@ -86,21 +99,32 @@ $(document).ready(function() { disp_mode = $(this).val(); }) + /** + * Attach the {@link appendInlineAnchor} function to a custom event, which + * will be triggered manually everytime the table of results is reloaded + */ $("#sqlqueryresults").live('appendAnchor',function() { appendInlineAnchor(disp_mode); }) + // Trigger the appendAnchor event to prepare the first table for inline edit $("#sqlqueryresults").trigger('appendAnchor'); + // Append the Toggle Query Box message to the query input form $('') .html(PMA_messages['strToggleQueryBox']) .appendTo("#sqlqueryform"); + // Attach the toggling of the query box visibility to a click $("#togglequerybox").live('click', function() { $(this).siblings().slideToggle("medium"); }) - //SQL Query Submit + /** + * Ajax Event handler for 'SQL Query Submit' + * + * @uses PMA_ajaxShowMessage() + */ $("#sqlqueryform").live('submit', function(event) { event.preventDefault(); @@ -122,13 +146,26 @@ $(document).ready(function() { $("#togglequerybox").trigger('click'); } } - }) + }) // end $.post() }) // end SQL Query submit - //Paginate the results table + /** + * Ajax Event handlers for Paginating the results table + * + * @uses PMA_ajaxShowMessage() + */ + + /** + * Paginate when we click any of the navigation buttons + */ $("input[name=navig]").live('click', function(event) { event.preventDefault(); + PMA_ajaxShowMessage(); + + /** + * @var the_form Object referring to the form element that paginates the results table + */ var the_form = $(this).parent("form"); $(the_form).append(''); @@ -136,22 +173,26 @@ $(document).ready(function() { $.post($(the_form).attr('action'), $(the_form).serialize(), function(data) { $("#sqlqueryresults").html(data); $("#sqlqueryresults").trigger('appendAnchor'); - }) + }) // end $.post() })// end Paginate results table - //Paginate results with Page Selector + /** + * Paginate results with Page Selector dropdown + */ $("#pageselector").live('change', function(event) { event.preventDefault(); - //PMA_ajaxShowMessage(); + PMA_ajaxShowMessage(); $.get($(this).attr('href'), $(this).serialize() + '&ajax_request=true', function(data) { $("#sqlqueryresults").html(data); $("#sqlqueryresults").trigger('appendAnchor'); - }) + }) // end $.get() })// end Paginate results with Page Selector - //Sort results table + /** + * Ajax Event handler for sorting the results table + */ $("#table_results").find("a[title=Sort]").live('click', function(event) { event.preventDefault(); @@ -160,23 +201,32 @@ $(document).ready(function() { $.get($(this).attr('href'), $(this).serialize() + '&ajax_request=true', function(data) { $("#sqlqueryresults").html(data); $("#sqlqueryresults").trigger('appendAnchor'); - }) + }) // end $.get() })//end Sort results table - //displayOptionsForm handler + /** + * Ajax Event handler for the display options + */ $("#displayOptionsForm").live('submit', function(event) { event.preventDefault(); $.post($(this).attr('action'), $(this).serialize() + '&ajax_request=true' , function(data) { $("#sqlqueryresults").html(data); $("#sqlqueryresults").trigger('appendAnchor'); - }) + }) // end $.post() }) //end displayOptionsForm handler - // Inline Edit + /** + * Ajax Event handlers for Inline Editing + * + * @uses PMA_ajaxShowMessage() + * @uses getFieldName() + */ - // On click, replace the current field with an input/textarea + /** + * On click, replace the current field with an input/textarea + */ $(".edit_row_anchor").live('click', function(event) { event.preventDefault(); @@ -184,8 +234,18 @@ $(document).ready(function() { // Initialize some variables if(disp_mode == 'vertical') { + /** + * @var this_row_index Index of the current in the parent + * Current is the inline edit anchor. + */ var this_row_index = $(this).index(); + /** + * @var input_siblings Object referring to all inline editable events from same row + */ var input_siblings = $(this).parents('tbody').find('tr').find('.data_inline_edit:nth('+this_row_index+')'); + /** + * @var where_clause String containing the WHERE clause to select this row + */ var where_clause = $(this).parents('tbody').find('tr').find('.where_clause:nth('+this_row_index+')').val(); } else { @@ -194,11 +254,22 @@ $(document).ready(function() { } $(input_siblings).each(function() { + /** + * @var data_value Current value of this field + */ var data_value = $(this).html(); // We need to retrieve the value from the server for truncated/relation fields // Find the field name + + /** + * @var this_field Object referring to this field () + */ var this_field = $(this); + /** + * @var field_name String containing the name of this field. + * @see getFieldName() + */ var field_name = getFieldName($(this), disp_mode); // In each input sibling, wrap the current value in a textarea @@ -213,6 +284,9 @@ $(document).ready(function() { else if($(this).is('.truncated, .transformed')) { //handle truncated/transformed values values + /** + * @var sql_query String containing the SQL query used to retrieve value of truncated/transformed data + */ var sql_query = 'SELECT ' + field_name + ' FROM ' + window.parent.table + ' WHERE ' + where_clause; // Make the Ajax call and get the data, wrap it and insert it @@ -231,13 +305,19 @@ $(document).ready(function() { else { PMA_ajaxShowMessage(data.error); } - }) + }) // end $.post() } else if($(this).is('.relation')) { //handle relations + /** + * @var curr_value String containing the current value of this relational field + */ var curr_value = $(this).find('a').text(); + /** + * @var post_params Object containing parameters for the POST request + */ var post_params = { 'ajax_request' : true, 'get_relational_values' : true, @@ -252,12 +332,18 @@ $(document).ready(function() { $(this_field).html(data.dropdown) .append(''+data_value+''); $(".original_data").hide(); - }) + }) // end $.post() } else if($(this).is('.enum')) { //handle enum fields + /** + * @var curr_value String containing the current value of this relational field + */ var curr_value = $(this).text(); + /** + * @var post_params Object containing parameters for the POST request + */ var post_params = { 'ajax_request' : true, 'get_enum_values' : true, @@ -272,7 +358,7 @@ $(document).ready(function() { $(this_field).html(data.dropdown) .append(''+data_value+''); $(".original_data").hide(); - }) + }) // end $.post() } else if($(this).is('.null')) { //handle null fields @@ -283,16 +369,31 @@ $(document).ready(function() { }) }) // End On click, replace the current field with an input/textarea - // After editing, clicking again should post data + /** + * After editing, clicking again should post data + */ $(".edit_row_anchor_active").live('click', function(event) { event.preventDefault(); + /** + * @var this_row Object referring to current row that is being edited + */ var this_row = $(this); // Initialize variables if(disp_mode == 'vertical') { + /** + * @var this_row_index Index of the current in the parent + * Current is the inline edit anchor. + */ var this_row_index = $(this).index(); + /** + * @var input_siblings Object referring to all inline editable events from same row + */ var input_siblings = $(this).parents('tbody').find('tr').find('.data_inline_edit:nth('+this_row_index+')'); + /** + * @var where_clause String containing the WHERE clause to select this row + */ var where_clause = $(this).parents('tbody').find('tr').find('.where_clause:nth('+this_row_index+')').val(); } else { @@ -300,6 +401,9 @@ $(document).ready(function() { var where_clause = $(this).parent('tr').find('.where_clause').val(); } + /** + * @var nonunique Boolean, whether this row is unique or not + */ if($(this).is('.nonunique')) { var nonunique = 0; } @@ -308,16 +412,38 @@ $(document).ready(function() { } // Collect values of all fields to submit, we don't know which changed + /** + * @var params_to_submit Array containing the name/value pairs of all fields + */ var params_to_submit = {}; + /** + * @var relation_fields Array containing the name/value pairs of relational fields + */ var relation_fields = {}; + /** + * @var transform_fields Array containing the name/value pairs for transformed fields + */ var transform_fields = {}; + /** + * @var transformation_fields Boolean, if there are any transformed fields in this row + */ var transformation_fields = false; $(input_siblings).each(function() { + /** + * @var this_field Object referring to this field () + */ var this_field = $(this); + /** + * @var field_name String containing the name of this field. + * @see getFieldName() + */ var field_name = getFieldName($(this), disp_mode); + /** + * @var this_field_params Array temporary storage for the name/value of current field + */ var this_field_params = {}; if($(this).is('.transformed')) { @@ -341,7 +467,9 @@ $(document).ready(function() { $.extend(params_to_submit, this_field_params); }) - //generate the SQL query to update this row + /** + * @var sql_query String containing the SQL query to update this row + */ var sql_query = 'UPDATE ' + window.parent.table + ' SET '; $.each(params_to_submit, function(key, value) { @@ -350,14 +478,24 @@ $(document).ready(function() { } sql_query += ' ' + key + "='" + value + "' , "; }) + //Remove the last ',' appended in the above loop sql_query = sql_query.replace(/,\s$/, ''); sql_query += ' WHERE ' + where_clause; + /** + * @var rel_fields_list String, url encoded representation of {@link relations_fields} + */ var rel_fields_list = $.param(relation_fields); - + + /** + * @var transform_fields_list String, url encoded representation of {@link transform_fields} + */ var transform_fields_list = $.param(transform_fields); // Make the Ajax post after setting all parameters + /** + * @var post_params Object containing parameters for the POST request + */ var post_params = {'ajax_request' : true, 'sql_query' : sql_query, 'disp_direction' : disp_mode, @@ -380,6 +518,9 @@ $(document).ready(function() { $(input_siblings).each(function() { // Inline edit post has been successful. if($(this).is(':not(.relation, .enum)')) { + /** + * @var new_html String containing value of the data field after edit + */ var new_html = $(this).find('textarea').val(); if($(this).is('.transformed')) { @@ -422,6 +563,6 @@ $(document).ready(function() { else { PMA_ajaxShowMessage(data.error); }; - }) + }) // end $.post() }) // End After editing, clicking again should post data -}) +}, 'top.frame_content') // end $(document).ready()