diff --git a/db_create.php b/db_create.php index db4f090ac..64a8acbff 100755 --- a/db_create.php +++ b/db_create.php @@ -42,6 +42,9 @@ if (! $result) { $GLOBALS['db'] = ''; $GLOBALS['table'] = ''; + /** + * If in an Ajax request, just display the message with {@link PMA_ajaxResponse} + */ if($GLOBALS['is_ajax_request'] == true) { PMA_ajaxResponse($message, FALSE); } @@ -53,29 +56,55 @@ if (! $result) { $message->addParam($new_db); $GLOBALS['db'] = $new_db; + /** + * If in an Ajax request, build the output and send it + */ if($GLOBALS['is_ajax_request'] == true) { + /** + * String containing the SQL Query formatted in pretty HTML + * @global array $GLOBALS['extra_data'] + * @name $extra_data + */ $extra_data['sql_query'] = PMA_showMessage(NULL, $sql_query, 'success'); //Construct the html for the new database, so that it can be appended to the list of databases on server_databases.php + /** + * Build the array to be passed to {@link PMA_generate_common_url} to generate the links + * @global array $GLOBALS['db_url_params'] + * @name $db_url_params + */ $db_url_params['db'] = $new_db; $is_superuser = PMA_isSuperuser(); + /** + * String that will contain the output HTML + * @name $new_db_string + */ $new_db_string = ''; + /** + * Is user allowed to drop the database? + */ if ($is_superuser || $cfg['AllowUserDropDatabase']) { $new_db_string .= ''; - $new_db_string .= ''; + $new_db_string .= ''; $new_db_string .=''; } + /** + * Link to the database's page + */ $new_db_string .= ''; $new_db_string .= ''; $new_db_string .= $new_db . ''; $new_db_string .= ''; + /** + * If the user has privileges, let him check privileges for the DB + */ if($is_superuser) { $db_url_params['checkprivs'] = $new_db; @@ -90,6 +119,8 @@ if (! $result) { $new_db_string .= ''; + /** @todo Statistics for newly created DB! */ + $extra_data['new_db_string'] = $new_db_string; PMA_ajaxResponse($message, true, $extra_data); diff --git a/db_operations.php b/db_operations.php index 86802f694..dbceae6eb 100755 --- a/db_operations.php +++ b/db_operations.php @@ -263,6 +263,10 @@ if (strlen($db) && (! empty($db_rename) || ! empty($db_copy))) { } } + /** + * Database has been successfully renamed/moved. If in an Ajax request, + * generate the output with {@link PMA_ajaxResponse} and exit + */ if( $GLOBALS['is_ajax_request'] == true) { $extra_data['newname'] = $newname; $extra_data['sql_query'] = PMA_showMessage(NULL, $sql_query); diff --git a/db_search.php b/db_search.php index 50e888038..208b3d284 100755 --- a/db_search.php +++ b/db_search.php @@ -111,7 +111,7 @@ if (empty($_REQUEST['field_str']) || ! is_string($_REQUEST['field_str'])) { } /** - * Displays top links + * Displays top links if we are not in an Ajax request */ $sub_part = ''; @@ -275,6 +275,9 @@ if (isset($_REQUEST['submit_search'])) { } } // end 1. +/** + * If we are in an Ajax request, we need to exit after displaying all the HTML + */ if($GLOBALS['is_ajax_request'] == true) { exit; } diff --git a/db_tracking.php b/db_tracking.php index d4a15b00a..62f855441 100755 --- a/db_tracking.php +++ b/db_tracking.php @@ -9,9 +9,12 @@ */ require_once './libraries/common.inc.php'; -//Get some js files needed for Ajax +//Get some js files needed for Ajax requests $GLOBALS['js_include'][] = 'jquery/jquery-ui-1.8.custom.js'; +/** + * If we are not in an Ajax request, then do the common work and show the links etc. + */ if($GLOBALS['is_ajax_request'] != true) { require './libraries/db_common.inc.php'; } @@ -26,6 +29,10 @@ require './libraries/db_info.inc.php'; if (isset($_REQUEST['delete_tracking']) && isset($_REQUEST['table'])) { PMA_Tracker::deleteTracking($GLOBALS['db'], $_REQUEST['table']); + /** + * If in an Ajax request, generate the success message and use + * {@link PMA_ajaxResponse()} to send the output + */ if($GLOBALS['is_ajax_request'] == true) { $message = PMA_Message::success(); PMA_ajaxResponse($message, true); diff --git a/js/functions.js b/js/functions.js index cdaa515b1..12521c8b4 100755 --- a/js/functions.js +++ b/js/functions.js @@ -1757,6 +1757,10 @@ function PMA_ajaxShowMessage(message, timeout) { return true; } + /** + * @var msg String containing the message that has to be displayed + * @default PMA_messages['strLoading'] + */ if(!message) { var msg = PMA_messages['strLoading']; } @@ -1764,6 +1768,10 @@ function PMA_ajaxShowMessage(message, timeout) { var msg = message; } + /** + * @var timeout Number of milliseconds for which {@link msg} will be visible + * @default 5000 ms + */ if(!timeout) { var to = 5000; } @@ -1772,6 +1780,7 @@ function PMA_ajaxShowMessage(message, timeout) { } if( !ajax_message_init) { + //For the first time this function is called, append a new div $(function(){ $('
') .insertBefore("#serverinfo"); @@ -1790,6 +1799,7 @@ function PMA_ajaxShowMessage(message, timeout) { ajax_message_init = true; } else { + //Otherwise, just show the div again after inserting the message $("#loading") .clearQueue() .html(msg) @@ -1804,7 +1814,8 @@ function PMA_ajaxShowMessage(message, timeout) { } /** - * jQuery function that uses jQueryUI's dialogs to confirm with user + * jQuery function that uses jQueryUI's dialogs to confirm with user. Does not + * return a jQuery object yet and hence cannot be chained * * @param string question * @param string url URL to be passed to the callbackFn to make @@ -1817,6 +1828,10 @@ jQuery.fn.PMA_confirm = function(question, url, callbackFn) { return true; } + /** + * @var button_options Object that stores the options passed to jQueryUI + * dialog + */ var button_options = {}; button_options[PMA_messages['strOK']] = function(){ $(this).dialog("close").remove(); @@ -1837,11 +1852,19 @@ jQuery.fn.PMA_confirm = function(question, url, callbackFn) { * Also fixes the even/odd classes of the table rows at the end. * * @param string text_selector string to select the sortKey's text + * + * @return jQuery Object for chaining purposes */ jQuery.fn.PMA_sort_table = function(text_selector) { return this.each(function() { + + /** + * @var table_body Object referring to the table's element + */ var table_body = $(this); - //collect all rows + /** + * @var rows Object referring to the collection of rows in {@link table_body} + */ var rows = $(this).find('tr').get(); //get the text of the field that we will sort by @@ -1860,7 +1883,7 @@ jQuery.fn.PMA_sort_table = function(text_selector) { return 0; }) - //pull out each row from the table and then append it according to it's order' + //pull out each row from the table and then append it according to it's order $.each(rows, function(index, row) { $(table_body).append(row); row.sortKey = null; @@ -1879,15 +1902,26 @@ jQuery.fn.PMA_sort_table = function(text_selector) { * jQuery coding for 'Create Table'. Used on db_operations.php, * db_structure.php and db_tracking.php (i.e., wherever * libraries/display_create_table.lib.php is used) + * + * Attach Ajax Event handlers for Create Table */ $(document).ready(function() { - //make Ajax call and create the dialog with the full create table form + /** + * Attach event handler to the submit action of the create table minimal form + * and retrieve the full table form and display it in a dialog + * + * @uses PMA_ajaxShowMessage() + */ $("#create_table_form_minimal").live('submit', function(event) { event.preventDefault(); /* @todo Validate this form! */ + /** + * @var button_options Object that stores the options passed to jQueryUI + * dialog + */ var button_options = {}; button_options[PMA_messages['strCancel']] = function() {$(this).dialog('close').remove();} @@ -1906,9 +1940,19 @@ $(document).ready(function() { }); + /** + * Attach event handler for submission of create table form + * + * @uses PMA_ajaxShowMessage() + * @uses $.PMA_sort_table() + * @uses window.parent.refreshNavigation() + */ $("#create_table_form").find("input[name=submit_num_fields], input[name=do_save_data]").live('click', function(event) { event.preventDefault(); + /** + * @var the_form object referring to the create table form + */ var the_form = $("#create_table_form"); PMA_ajaxShowMessage(PMA_messages['strProcessingRequest']); @@ -1918,7 +1962,6 @@ $(document).ready(function() { //User wants to add more fields to the table $.post($(the_form).attr('action'), $(the_form).serialize() + "&submit_num_fields=" + $(this).val(), function(data) { $("#create_table_dialog").html(data); - }) //end $.post() } else if($(this).attr('name') == 'do_save_data') { @@ -1928,12 +1971,30 @@ $(document).ready(function() { PMA_ajaxShowMessage(data.message); $("#create_table_dialog").dialog("close").remove(); + /** + * @var tables_table Object referring to the element that holds the list of tables + */ var tables_table = $("#tablesForm").find("tbody").not("#tbl_summary_row"); + /** + * @var curr_last_row Object referring to the last element in {@link tables_table} + */ var curr_last_row = $(tables_table).find('tr:last'); + /** + * @var curr_last_row_index_string String containing the index of {@link curr_last_row} + */ var curr_last_row_index_string = $(curr_last_row).find('input:checkbox').attr('id').match(/\d+/)[0]; + /** + * @var curr_last_row_index Index of {@link curr_last_row} + */ var curr_last_row_index = parseFloat(curr_last_row_index_string); + /** + * @var new_last_row_index Index of the new row to be appended to {@link tables_table} + */ var new_last_row_index = curr_last_row_index + 1; + /** + * @var new_last_row_id String containing the id of the row to be appended to {@link tables_table} + */ var new_last_row_id = 'checkbox_tbl_' + new_last_row_index; //append to table @@ -1943,33 +2004,39 @@ $(document).ready(function() { .end() .appendTo(tables_table); + //Sort the table $(tables_table).PMA_sort_table('th'); - //sort the table - //PMA_sort_table(tables_table, 'th'); - - //Refresh navigation frame + //Refresh navigation frame as a new table has been added window.parent.refreshNavigation(); } else { PMA_ajaxShowMessage(data.error); } }) // end $.post() - } + } // end elseif() }) // end create table form submit button actions }, 'top.frame_content'); //end $(document).ready for 'Create Table' /** - * jQuery coding for Empty Table and Drop Table. Used wherever libraries/ + * Attach event handlers for Empty Table and Drop Table. Used wherever libraries/ * tbl_links.inc.php is used. */ $(document).ready(function() { - //Empty Table + /** + * Attach Ajax event handlers for Empty Table + * + * @uses PMA_ajaxShowMessage() + * @uses $.PMA_confirm() + */ $("#empty_table_anchor").live('click', function(event) { event.preventDefault(); + /** + * @var question String containing the question to be asked for confirmation + */ var question = 'TRUNCATE TABLE ' + window.parent.table; $(this).PMA_confirm(question, $(this).attr('href'), function(url) { @@ -1988,13 +2055,22 @@ $(document).ready(function() { PMA_ajaxShowMessage(data.error); } }) // end $.get - }) + }) // end $.PMA_confirm() }) // end Empty Table - //Drop Table + /** + * Attach Ajax event handler for Drop Table + * + * @uses PMA_ajaxShowMessage() + * @uses $.PMA_confirm() + * @uses window.parent.refreshNavigation() + */ $("#drop_table_anchor").live('click', function(event) { event.preventDefault(); + /** + * @var question String containing the question to be asked for confirmation + */ var question = 'DROP TABLE/VIEW ' + window.parent.table; $(this).PMA_confirm(question, $(this).attr('href'), function(url) { @@ -2014,19 +2090,25 @@ $(document).ready(function() { PMA_ajaxShowMessage(data.error); } }) // end $.get - }) - }) + }) // end $.PMA_confirm() + }) // end $().live() }, 'top.frame_content'); //end $(document).ready() for libraries/tbl_links.inc.php /** - * jQuery coding for Drop Trigger. Used on tbl_structure.php + * Attach Ajax event handlers for Drop Trigger. Used on tbl_structure.php */ $(document).ready(function() { $(".drop_trigger_anchor").live('click', function(event) { event.preventDefault(); + /** + * @var curr_row Object reference to the current trigger's + */ var curr_row = $(this).parents('tr'); + /** + * @var question String containing the question to be asked for confirmation + */ var question = 'DROP TRIGGER IF EXISTS `' + $(curr_row).children('td:first').text() + '`'; $(this).PMA_confirm(question, $(this).attr('href'), function(url) { @@ -2045,22 +2127,28 @@ $(document).ready(function() { else { PMA_ajaxShowMessage(data.error); } - }) // end $.get - }) - }) + }) // end $.get() + }) // end $.PMA_confirm() + }) // end $().live() }, 'top.frame_content'); //end $(document).ready() for Drop Trigger /** - * jQuery coding for Drop Database. Moved here from db_structure.js as it was - * also required on db_create.php - * + * Attach Ajax event handlers for Drop Database. Moved here from db_structure.js + * as it was also required on db_create.php + * + * @uses $.PMA_confirm() + * @uses PMA_ajaxShowMessage() + * @uses window.parent.refreshNavigation() + * @uses window.parent.refreshMain() */ $(document).ready(function() { - //Drop Database $("#drop_db_anchor").live('click', function(event) { event.preventDefault(); //context is top.frame_content, so we need to use window.parent.db to access the db var + /** + * @var question String containing the question to be asked for confirmation + */ var question = PMA_messages['strDropDatabaseStrongWarning'] + '\n' + PMA_messages['strDoYouReally'] + ' :\n' + 'DROP DATABASE ' + window.parent.db; $(this).PMA_confirm(question, $(this).attr('href') ,function(url) { @@ -2070,14 +2158,16 @@ $(document).ready(function() { //Database deleted successfully, refresh both the frames window.parent.refreshNavigation(); window.parent.refreshMain(); - }) - }); + }) // end $.get() + }); // end $.PMA_confirm() }); //end of Drop Database Ajax action -}) +}) // end of $(document).ready() for Drop Database /** - * jQuery coding for 'Create Database'. Used wherever libraries/ + * Attach Ajax event handlers for 'Create Database'. Used wherever libraries/ * display_create_database.lib.php is used, ie main.php and server_databases.php + * + * @uses PMA_ajaxShowMessage() */ $(document).ready(function() { @@ -2103,18 +2193,24 @@ $(document).ready(function() { else { PMA_ajaxShowMessage(data.error); } - }) - }) -}) + }) // end $.post() + }) // end $().live() +}) // end $(document).ready() for Create Database /** - * jQuery coding for 'Change Password' on main.php + * Attach Ajax event handlers for 'Change Password' on main.php */ $(document).ready(function() { + /** + * Attach Ajax event handler on the change password anchor + */ $('#change_password_anchor').live('click', function(event) { event.preventDefault(); + /** + * @var button_options Object containing options to be passed to jQueryUI's dialog + */ var button_options = {}; button_options[PMA_messages['strCancel']] = function() {$(this).dialog('close').remove();} @@ -2127,12 +2223,20 @@ $(document).ready(function() { buttons : button_options }) .append(data); - }) - }) + }) // end $.get() + }) // end handler for change password anchor + /** + * Attach Ajax event handler for Change Password form submission + * + * @uses PMA_ajaxShowMessage() + */ $("#change_password_form").find('input[name=change_pw]').live('click', function(event) { event.preventDefault(); + /** + * @var the_form Object referring to the change password form + */ var the_form = $("#change_password_form"); PMA_ajaxShowMessage(PMA_messages['strProcessingRequest']); @@ -2150,6 +2254,6 @@ $(document).ready(function() { else { PMA_ajaxShowMessage(data.error); } - }) - }) -}) + }) // end $.post() + }) // end handler for Change Password form submission +}) // end $(document).ready() for Change Password diff --git a/js/sql.js b/js/sql.js index 2a3250aff..ec32b3794 100644 --- a/js/sql.js +++ b/js/sql.js @@ -40,7 +40,7 @@ function getFieldName(this_field_obj, disp_mode) { * The function that iterates over each row in the table_results and appends a * new inline edit anchor to each table row. * - * @param string disp_mode + * @param disp_mode string */ function appendInlineAnchor(disp_mode) { if(disp_mode == 'vertical') { @@ -78,18 +78,33 @@ function appendInlineAnchor(disp_mode) { } } +/**#@+ + * @memberOf jQuery + * @namespace jQuery + */ + /** - * Ajax scripts for sql and browse pages + * @description

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 + * + * + * @name document.ready + * @function + * @augments jQuery.fn */ $(document).ready(function() { + /** + * @lends jQuery + */ + /** * @var disp_mode current value of the direction in which the table is displayed */ @@ -102,6 +117,8 @@ $(document).ready(function() { /** * Attach the {@link appendInlineAnchor} function to a custom event, which * will be triggered manually everytime the table of results is reloaded + * @function + * @name sqlqueryresults_live */ $("#sqlqueryresults").live('appendAnchor',function() { appendInlineAnchor(disp_mode); @@ -123,7 +140,8 @@ $(document).ready(function() { /** * Ajax Event handler for 'SQL Query Submit' * - * @uses PMA_ajaxShowMessage() + * @see PMA_ajaxShowMessage() + * @inner */ $("#sqlqueryform").live('submit', function(event) { event.preventDefault(); @@ -220,8 +238,8 @@ $(document).ready(function() { /** * Ajax Event handlers for Inline Editing * - * @uses PMA_ajaxShowMessage() - * @uses getFieldName() + * @see PMA_ajaxShowMessage() + * @see getFieldName() */ /** @@ -566,3 +584,5 @@ $(document).ready(function() { }) // end $.post() }) // End After editing, clicking again should post data }, 'top.frame_content') // end $(document).ready() + +/**#@- */ diff --git a/js/tbl_change.js b/js/tbl_change.js index c1c585bd0..a092171cd 100755 --- a/js/tbl_change.js +++ b/js/tbl_change.js @@ -1,6 +1,10 @@ /* vim: set expandtab sw=4 ts=4 sts=4: */ /** - * function used in table data manipulation pages + * @fileoverview function used in table data manipulation pages + * + * @requires jQuery + * @requires jQueryUI + * @requires js/functions.js * * @version $Id$ */ @@ -249,13 +253,24 @@ function unNullify(urlField, multi_edit) } // end of the 'unNullify()' function /** - * Ajax handlers for this page + * Ajax handlers for Change Table page + * + * Actions Ajaxified here: + * Submit Data to be inserted into the table + * Restart insertion with 'N' rows. */ $(document).ready(function() { - //Submission of data to be inserted into table + /** + * Submission of data to be inserted into table + * + * @uses PMA_ajaxShowMessage() + */ $("#insertForm").live('submit', function(event) { + /** + * @var the_form Object referring to the insertion form + */ var the_form = $(this); event.preventDefault(); @@ -265,6 +280,7 @@ $(document).ready(function() { $.post($(the_form).attr('action'), $(the_form).serialize(), function(data) { if(data.success == true) { PMA_ajaxShowMessage(data.message); + $("#topmenucontainer") .next('div') .remove() @@ -277,6 +293,7 @@ $(document).ready(function() { $(notice_class).remove(); } + //Clear the data in the forms $(the_form).find('input:reset').trigger('click'); } else { @@ -285,15 +302,27 @@ $(document).ready(function() { }) }) // end submission of data to be inserted into table - //Restart Insertion form + /** + * Restart Insertion form + */ $("#insert_rows").live('change', function(event) { event.preventDefault(); + /** + * @var curr_rows Number of current insert rows already on page + */ var curr_rows = $(".insertRowTable").length; + /** + * @var target_rows Number of rows the user wants + */ var target_rows = $("#insert_rows").val(); if(curr_rows < target_rows ) { while( curr_rows < target_rows ) { + + /** + * @var last_row Object referring to the last row + */ var last_row = $("#insertForm").find(".insertRowTable:last"); //Clone the insert tables @@ -308,17 +337,20 @@ $(document).ready(function() { * name is of format funcs[multi_edit][10][] */ + /** + * @var this_name String containing name of the input/select elements + */ var this_name = $(this).attr('name'); - //split at [10], so we have the parts that can be concatenated later + /** split {@link this_name} at [10], so we have the parts that can be concatenated later */ var name_parts = this_name.split(/\[\d+\]/); - //extract the [10] + /** extract the [10] from {@link name_parts} */ var old_row_index_string = this_name.match(/\[\d+\]/)[0]; - //extract 10 - had to split into two steps to accomodate double digits + /** extract 10 - had to split into two steps to accomodate double digits */ var old_row_index = parseInt(old_row_index_string.match(/\d+/)[0]); - //calculate next index i.e. 11 + /** calculate next index i.e. 11 */ var new_row_index = old_row_index + 1; - //generate the new name i.e. funcs[multi_edit][11][foobarbaz] + /** generate the new name i.e. funcs[multi_edit][11][foobarbaz] */ var new_name = name_parts[0] + '[' + new_row_index + ']' + name_parts[1]; $(this).attr('name', new_name); @@ -331,10 +363,17 @@ $(document).ready(function() { .after(''); } else { + + /** + * @var last_checkbox Object reference to the last checkbox in #insertForm + */ var last_checkbox = $("#insertForm").children('input:checkbox:last'); + /** name of {@link last_checkbox} */ var last_checkbox_name = $(last_checkbox).attr('name'); + /** index of {@link last_checkbox} */ var last_checkbox_index = parseInt(last_checkbox_name.match(/\d+/)); + /** name of new {@link last_checkbox} */ var new_name = last_checkbox_name.replace(/\d+/,last_checkbox_index+1); $(last_checkbox) @@ -359,4 +398,4 @@ $(document).ready(function() { } } }) -}, 'top.frame_content'); //end Ajax handlers \ No newline at end of file +}, 'top.frame_content'); //end $(document).ready() \ No newline at end of file diff --git a/js/tbl_select.js b/js/tbl_select.js index 8541a84e0..88796bcfc 100644 --- a/js/tbl_select.js +++ b/js/tbl_select.js @@ -1,8 +1,23 @@ /** - * JavaScript functions used on tbl_select.php + * @fileoverview JavaScript functions used on tbl_select.php + * + * @requires jQuery + * @requires js/functions.js + */ + +/** + * Ajax event handlers for this page + * + * Actions ajaxified here: + * Table Search */ $(document).ready(function() { + /** + * Ajax event handler for Table Search + * + * @uses PMA_ajaxShowMessage() + */ $("#tbl_search_form").live('submit', function(event) { event.preventDefault(); @@ -14,4 +29,4 @@ $(document).ready(function() { $("#searchresults").html(data); }) }) -}, 'top.frame_content'); \ No newline at end of file +}, 'top.frame_content'); // end $(document).ready() \ No newline at end of file