From 1351f3743c85b045c9f83bdc5db4882a57e7bfef Mon Sep 17 00:00:00 2001 From: Eston Bond Date: Mon, 22 Nov 2010 18:01:01 -0800 Subject: [PATCH] Monday is code tedium day: commenting the editor --- .../javascript/gollum-editor/gollum.editor.js | 525 ++++++++++++------ 1 file changed, 347 insertions(+), 178 deletions(-) diff --git a/lib/gollum/frontend/public/javascript/gollum-editor/gollum.editor.js b/lib/gollum/frontend/public/javascript/gollum-editor/gollum.editor.js index fea1b74a..780a9384 100644 --- a/lib/gollum/frontend/public/javascript/gollum-editor/gollum.editor.js +++ b/lib/gollum/frontend/public/javascript/gollum-editor/gollum.editor.js @@ -269,10 +269,26 @@ $('#gollum-editor-body').length ); }, + + /** + * EditorHas.collapsibleInputs + * True if the editor contains collapsible inputs for things like the + * sidebar or footer, false otherwise. + * + * @return boolean + */ collapsibleInputs: function() { return $('#gollum-editor .collapsed, #gollum-editor .expanded').length; }, + + /** + * EditorHas.formatSelector + * True if the editor has a format selector (for switching between + * language types), false otherwise. + * + * @return boolean + */ formatSelector: function() { return $('#gollum-editor-format-selector select').length; }, @@ -301,24 +317,60 @@ return ( ua.test( navigator.userAgent ) ); }, + + /** + * EditorHas.editSummaryMarkup + * True if the editor has a summary field (Gollum's commit message), + * false otherwise. + * + * @return boolean + */ editSummaryMarkup: function() { return ( $('input#gollum-editor-message-field').length > 0 ); }, + + /** + * EditorHas.help + * True if the editor contains the inline help sector, false otherwise. + * + * @return boolean + */ help: function() { return ( $('#gollum-editor #gollum-editor-help').length && $('#gollum-editor #function-help').length ); }, + + /** + * EditorHas.mathJax + * True if the editor has MathJax enabled and running, false otherwise. + * + * @return boolean + */ mathJax: function() { //TODO return false; }, + + /** + * EditorHas.previewButton + * True if the editor has a preview button, false otherwise. + * + * @return boolean + */ previewButton: function() { return ( $('#gollum-editor #gollum-editor-preview').length ); }, + + /** + * EditorHas.titleDisplayed + * True if the editor is displaying a title field, false otherwise. + * + * @return boolean + */ titleDisplayed: function() { return ( ActiveOptions.NewFile ); } @@ -504,15 +556,36 @@ }; + + /** + * FormatSelector + * + * Functions relating to the format selector (if it exists) + */ var FormatSelector = { $_SELECTOR: null, + /** + * FormatSelector.evtChangeFormat + * Event handler for when a format has been changed by the format + * selector. Will automatically load a new language definition + * via JS if necessary. + * + * @return void + */ evtChangeFormat: function( e ) { var newMarkup = $(this).val(); LanguageDefinition.setActiveLanguage( newMarkup ); }, + + /** + * FormatSelector.init + * Initializes the format selector. + * + * @return void + */ init: function( $sel ) { debug('Initializing format selector'); @@ -528,197 +601,293 @@ - var Help = { + /** + * Help + * + * Functions that manage the display and loading of inline help files. + */ + var Help = { - _ACTIVE_HELP: '', - _LOADED_HELP_LANGS: [], - _HELP: {}, - - define: function( name, definitionObject ) { - if ( Help.isValidHelpFormat( definitionObject ) ) { - debug('help is a valid format'); - - Help._ACTIVE_HELP_LANG = name; - Help._LOADED_HELP_LANGS.push( name ); - Help._HELP[name] = definitionObject; - - if ( $("#function-help").length ) { - if ( $('#function-help').hasClass('disabled') ) { - $('#function-help').removeClass('disabled'); - } - $('#function-help').unbind('click'); - $('#function-help').click( Help.evtHelpButtonClick ); - - // generate help menus - Help.generateHelpMenuFor( name ); - } - } else { - if ( $('#function-help').length ) { - $('#function-help').addClass('disabled'); - } - } - }, - - generateHelpMenuFor: function( name ) { - if ( !Help._HELP[name] ) { - debug('Help is not defined for ' + name.toString()); - return false; - } - var helpData = Help._HELP[name]; - - // add MathJax Help if we have it - // TODO - if ( EditorHas.mathJax() && Help.isLoadedFor('mathjax') ) { - debug('Adding MathJax support to help'); - // TODO - } - - // clear this shiz out - $('#gollum-editor-help-parent').html(''); - $('#gollum-editor-help-list').html(''); - $('#gollum-editor-help-content').html(''); - - // go go inefficient algorithm - for ( var i=0; i < helpData.length; i++ ) { - if ( typeof helpData[i] != 'object' ) break; - - var $newLi = $('
  • ' + - helpData[i].menuName + '
    • '); - $('#gollum-editor-help-parent').append( $newLi ); - if ( i == 0 ) { - // select on first run - $newLi.children('a').addClass('selected'); - } - $newLi.children('a').click( Help.evtParentMenuClick ); - } - - // generate parent submenu on first run - Help.generateSubMenu( helpData[0], 0 ); - $($('#gollum-editor-help-list li a').get(0)).click(); - - }, - - generateSubMenu: function( subData, index ) { - $('#gollum-editor-help-list').html(''); - $('#gollum-editor-help-content').html(''); - for ( var i=0; i < subData.content.length; i++ ) { - if ( typeof subData.content[i] != 'object' ) break; - - var $subLi = $('
  • ' + - subData.content[i].menuName + '
    • '); - - - $('#gollum-editor-help-list').append( $subLi ); - $subLi.children('a').click( Help.evtSubMenuClick ); - } - }, - - showHelpFor: function( index1, index2 ) { - var html = - Help._HELP[Help._ACTIVE_HELP_LANG][index1].content[index2].data; - $('#gollum-editor-help-content').html(html); - }, - - isLoadedFor: function( name ) { - for ( var i=0; i < Help._LOADED_HELP_LANGS.length; i++ ) { - if ( name == Help._LOADED_HELP_LANGS[i] ) { - return true; - } - } - return false; - }, - - isValidHelpFormat: function( helpArr ) { - return ( typeof helpArr == 'object' && - helpArr.length && - typeof helpArr[0].menuName == 'string' && - typeof helpArr[0].content == 'object' && - helpArr[0].content.length ); - }, - - setActiveHelp: function( name ) { - if ( !Help.isLoadedFor( name ) ) { - if ( $('#function-help').length ) { - $('#function-help').addClass('disabled'); - } - } else { - Help._ACTIVE_HELP_LANG = name; - if ( $("#function-help").length ) { - if ( $('#function-help').hasClass('disabled') ) { - $('#function-help').removeClass('disabled'); - } - $('#function-help').unbind('click'); - $('#function-help').click( Help.evtHelpButtonClick ); - Help.generateHelpMenuFor( name ); - } - } - }, - - evtHelpButtonClick: function( e ) { - e.preventDefault(); - - // cascaded animations are prettier - if ( $('#gollum-editor-help').is(':visible') ) { - $('#gollum-editor-help').animate({ - opacity: 0 - }, 200, - function() { - $('#gollum-editor-help') - .animate({ height: 'hide' }, 200); - }); - } else { - $('#gollum-editor-help').animate({ - height: 'show' - }, 200, - function() { - $('#gollum-editor-help') - .animate({ opacity: 1 }, 300); - }); - } - }, - - evtParentMenuClick: function( e ) { - e.preventDefault(); - // short circuit if we've selected this already - if ( $(this).hasClass('selected') ) return; - - // populate from help data for this - var helpIndex = $(this).attr('rel'); - var subData = Help._HELP[Help._ACTIVE_HELP_LANG][helpIndex]; - - $('#gollum-editor-help-parent li a').removeClass('selected'); - $(this).addClass('selected'); - Help.generateSubMenu( subData, helpIndex ); - $($('#gollum-editor-help-list li a').get(0)).click(); - }, - - evtSubMenuClick: function( e ) { - e.preventDefault(); - if ( $(this).hasClass('selected') ) return; - - // split index rel data - var rawIndex = $(this).attr('rel').split(':'); - $('#gollum-editor-help-list li a').removeClass('selected'); - $(this).addClass('selected'); - Help.showHelpFor( rawIndex[0], rawIndex[1] ); - } - - }; + _ACTIVE_HELP: '', + _LOADED_HELP_LANGS: [], + _HELP: {}, /** - * $.GollumEditor.Dialog - * Used in exec() to display dialogs with dynamic fields. + * Help.define * + * Defines a new help context and enables the help function if it + * exists in the Gollum Function Bar. + * + * @param string name The name you're giving to this help context. + * Generally, this should match the language name. + * @param object definitionObject The definition object being loaded from a + * language / help definition file. + * @return void */ + define: function( name, definitionObject ) { + if ( Help.isValidHelpFormat( definitionObject ) ) { + debug('help is a valid format'); + + Help._ACTIVE_HELP_LANG = name; + Help._LOADED_HELP_LANGS.push( name ); + Help._HELP[name] = definitionObject; + + if ( $("#function-help").length ) { + if ( $('#function-help').hasClass('disabled') ) { + $('#function-help').removeClass('disabled'); + } + $('#function-help').unbind('click'); + $('#function-help').click( Help.evtHelpButtonClick ); + + // generate help menus + Help.generateHelpMenuFor( name ); + } + } else { + if ( $('#function-help').length ) { + $('#function-help').addClass('disabled'); + } + } + }, + + + /** + * Help.generateHelpMenuFor + * Generates the markup for the main help menu given a context name. + * + * @param string name The context name. + * @return void + */ + generateHelpMenuFor: function( name ) { + if ( !Help._HELP[name] ) { + debug('Help is not defined for ' + name.toString()); + return false; + } + var helpData = Help._HELP[name]; + + // add MathJax Help if we have it + // TODO + if ( EditorHas.mathJax() && Help.isLoadedFor('mathjax') ) { + debug('Adding MathJax support to help'); + // TODO + } + + // clear this shiz out + $('#gollum-editor-help-parent').html(''); + $('#gollum-editor-help-list').html(''); + $('#gollum-editor-help-content').html(''); + + // go go inefficient algorithm + for ( var i=0; i < helpData.length; i++ ) { + if ( typeof helpData[i] != 'object' ) break; + + var $newLi = $('
  • ' + + helpData[i].menuName + '
    • '); + $('#gollum-editor-help-parent').append( $newLi ); + if ( i == 0 ) { + // select on first run + $newLi.children('a').addClass('selected'); + } + $newLi.children('a').click( Help.evtParentMenuClick ); + } + + // generate parent submenu on first run + Help.generateSubMenu( helpData[0], 0 ); + $($('#gollum-editor-help-list li a').get(0)).click(); + + }, + + + /** + * Help.generateSubMenu + * Generates the markup for the inline help sub-menu given the data + * object for the submenu and the array index to start at. + * + * @param object subData The data for the sub-menu. + * @param integer index The index clicked on (parent menu index). + * @return void + */ + generateSubMenu: function( subData, index ) { + $('#gollum-editor-help-list').html(''); + $('#gollum-editor-help-content').html(''); + for ( var i=0; i < subData.content.length; i++ ) { + if ( typeof subData.content[i] != 'object' ) break; + + var $subLi = $('
  • ' + + subData.content[i].menuName + '
    • '); + + + $('#gollum-editor-help-list').append( $subLi ); + $subLi.children('a').click( Help.evtSubMenuClick ); + } + }, + + + /** + * Help.showHelpFor + * Displays the actual help content given the two menu indexes, which are + * rendered in the rel="" attributes of the help menus + * + * @param integer index1 parent index + * @param integer index2 submenu index + * @return void + */ + showHelpFor: function( index1, index2 ) { + var html = + Help._HELP[Help._ACTIVE_HELP_LANG][index1].content[index2].data; + $('#gollum-editor-help-content').html(html); + }, + + + /** + * Help.isLoadedFor + * Returns true if help is loaded for a specific markup language, + * false otherwise. + * + * @param string name The name of the markup language. + * @return boolean + */ + isLoadedFor: function( name ) { + for ( var i=0; i < Help._LOADED_HELP_LANGS.length; i++ ) { + if ( name == Help._LOADED_HELP_LANGS[i] ) { + return true; + } + } + return false; + }, + + + /** + * Help.isValidHelpFormat + * Does a quick check to make sure that the help definition isn't in a + * completely messed-up format. + * + * @param object (Array) helpArr The help definition array. + * @return boolean + */ + isValidHelpFormat: function( helpArr ) { + return ( typeof helpArr == 'object' && + helpArr.length && + typeof helpArr[0].menuName == 'string' && + typeof helpArr[0].content == 'object' && + helpArr[0].content.length ); + }, + + + /** + * Help.setActiveHelp + * Sets the active help definition to the one defined in the argument, + * re-rendering the help menu to match the new definition. + * + * @param string name The name of the help definition. + * @return void + */ + setActiveHelp: function( name ) { + if ( !Help.isLoadedFor( name ) ) { + if ( $('#function-help').length ) { + $('#function-help').addClass('disabled'); + } + } else { + Help._ACTIVE_HELP_LANG = name; + if ( $("#function-help").length ) { + if ( $('#function-help').hasClass('disabled') ) { + $('#function-help').removeClass('disabled'); + } + $('#function-help').unbind('click'); + $('#function-help').click( Help.evtHelpButtonClick ); + Help.generateHelpMenuFor( name ); + } + } + }, + + + /** + * Help.evtHelpButtonClick + * Event handler for clicking the help button in the function bar. + * + * @param jQuery.Event e The jQuery event object. + * @return void + */ + evtHelpButtonClick: function( e ) { + e.preventDefault(); + + // cascaded animations are prettier + if ( $('#gollum-editor-help').is(':visible') ) { + $('#gollum-editor-help').animate({ + opacity: 0 + }, 200, + function() { + $('#gollum-editor-help') + .animate({ height: 'hide' }, 200); + }); + } else { + $('#gollum-editor-help').animate({ + height: 'show' + }, 200, + function() { + $('#gollum-editor-help') + .animate({ opacity: 1 }, 300); + }); + } + }, + + + /** + * Help.evtParentMenuClick + * Event handler for clicking on an item in the parent menu. Automatically + * renders the submenu for the parent menu as well as the first result for + * the actual plain text. + * + * @param jQuery.Event e The jQuery event object. + * @return void + */ + evtParentMenuClick: function( e ) { + e.preventDefault(); + // short circuit if we've selected this already + if ( $(this).hasClass('selected') ) return; + + // populate from help data for this + var helpIndex = $(this).attr('rel'); + var subData = Help._HELP[Help._ACTIVE_HELP_LANG][helpIndex]; + + $('#gollum-editor-help-parent li a').removeClass('selected'); + $(this).addClass('selected'); + Help.generateSubMenu( subData, helpIndex ); + $($('#gollum-editor-help-list li a').get(0)).click(); + }, + + + /** + * Help.evtSubMenuClick + * Event handler for clicking an item in a help submenu. Renders the + * appropriate text for the submenu link. + * + * @param jQuery.Event e The jQuery event object. + * @return void + */ + evtSubMenuClick: function( e ) { + e.preventDefault(); + if ( $(this).hasClass('selected') ) return; + + // split index rel data + var rawIndex = $(this).attr('rel').split(':'); + $('#gollum-editor-help-list li a').removeClass('selected'); + $(this).addClass('selected'); + Help.showHelpFor( rawIndex[0], rawIndex[1] ); + } + }; + + + // Publicly-accessible function to Help.define $.GollumEditor.defineHelp = Help.define; - // Dialog is separate too + // Dialog exists as its own thing now $.GollumEditor.Dialog = $.GollumDialog; $.GollumEditor.replaceSelection = function( repText ) { FunctionBar.replaceFieldSelection( $('#gollum-editor-body'), repText ); } + // Placeholder exists as its own thing now $.GollumEditor.Placeholder = $.GollumPlaceholder; })(jQuery);