From c5895ca8340c049875c754d9d8b21436ee665dab Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Sat, 21 Nov 2009 02:37:41 +0000
Subject: [PATCH] MINOR Documentation for CMSMain.js and LeftAndMain.js

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/cms/trunk@92633 467b73ca-7a2a-4603-9d3b-597d59a354a9
---
 javascript/CMSMain.js     | 65 ++++++++++++++++++++++-------
 javascript/LeftAndMain.js | 88 ++++++++++++++++++++++-----------------
 2 files changed, 99 insertions(+), 54 deletions(-)

diff --git a/javascript/CMSMain.js b/javascript/CMSMain.js
index bda15e2a..7e7f2d59 100644
--- a/javascript/CMSMain.js
+++ b/javascript/CMSMain.js
@@ -5,13 +5,22 @@
 var ss_MainLayout;
 
 (function($) {
-	$('body.CMSMain').concrete('ss', function($){return{
+	
+	/**
+	 * @class Layout handling for the main CMS interface,
+	 * with tree on left and main edit form on the right.
+	 * @name ss.CMSMain
+	 */
+	$('body.CMSMain').concrete('ss', function($){return
+		/** @lends ss.CMSMain */
+		{
 
 		/**
 		 * Reference to jQuery.layout element
+		 * @type Object
 		 */
 		MainLayout: null,
-		
+
 		onmatch: function() {
 			var self = this;
 
@@ -107,9 +116,12 @@ var ss_MainLayout;
 	}});
 	
 	/**
-	 * CMS-specific form behaviour
+	 * @class CMS-specific form behaviour
+	 * @name ss.EditForm
 	 */
-	$('#Form_EditForm').concrete('ss', function($){return{
+	$('#Form_EditForm').concrete('ss', function($){return
+		/** @lends ss.EditForm */
+		{
 		onmatch: function() {
 			// Alert the user on change of page-type - this might have implications
 			// on the available form fields etc.
@@ -124,10 +136,13 @@ var ss_MainLayout;
 	}});
 	
 	/**
-	 * ParentType / ParentID field combination - mostly toggling between
+	 * @class ParentID field combination - mostly toggling between
 	 * the two radiobuttons and setting the hidden "ParentID" field
+	 * @name ss.EditForm.ParentType
 	 */
-	$('#Form_EditForm_ParentType').concrete('ss', function($){return{
+	$('#Form_EditForm_ParentType').concrete('ss', function($){return
+		/** @lends ss.EditForm.ParentType */
+		{
 		onmatch : function() {
 			var parentTypeRootEl = $('#Form_EditForm_ParentType_root');
 			var parentTypeSubpageEl = $('#Form_EditForm_ParentType_subpage');
@@ -156,10 +171,13 @@ var ss_MainLayout;
 	}});
 	
 	/**
-	 * Email containing the link to the archived version of the page.
+	 * @class Email containing the link to the archived version of the page.
 	 * Visible on readonly older versions of a specific page at the moment.
+	 * @name ss.Form_EditForm_action_email
 	 */
-	$('#Form_EditForm .Actions #Form_EditForm_action_email').concrete('ss', function($){return{
+	$('#Form_EditForm .Actions #Form_EditForm_action_email').concrete('ss', function($){return
+		/** @lends ss.Form_EditForm_action_email */
+		{
 		onclick: function(e) {
 			window.open(
 				'mailto:?subject=' 
@@ -174,10 +192,13 @@ var ss_MainLayout;
 	}});
 
 	/**
-	 * Open a printable representation of the form in a new window.
+	 * @class Open a printable representation of the form in a new window.
 	 * Used for readonly older versions of a specific page.
+	 * @name ss.Form_EditForm_action_print
 	 */
-	$('#Form_EditForm .Actions #Form_EditForm_action_print').concrete('ss', function($){return{
+	$('#Form_EditForm .Actions #Form_EditForm_action_print').concrete('ss', function($){return
+		/** @lends ss.Form_EditForm_action_print */
+		{
 		onclick: function(e) {
 			var printURL = $(this[0].form).attr('action').replace(/\?.*$/,'') 
 				+ '/printable/' 
@@ -191,9 +212,12 @@ var ss_MainLayout;
 	}});
 	
 	/**
-	 * A "rollback" to a specific version needs user confirmation.
+	 * @class A "rollback" to a specific version needs user confirmation.
+	 * @name ss.Form_EditForm_action_rollback
 	 */
-	$('#Form_EditForm .Actions #Form_EditForm_action_rollback').concrete('ss', function($){return{
+	$('#Form_EditForm .Actions #Form_EditForm_action_rollback').concrete('ss', function($){return
+		/** @lends ss.Form_EditForm_action_rollback */
+		{
 		onclick: function(e) {
 			// @todo i18n
 			return confirm("Do you really want to copy the published content to the stage site?");
@@ -201,9 +225,12 @@ var ss_MainLayout;
 	}});
 	
 	/**
-	 * All forms in the right content panel should have closeable jQuery UI style titles.
+	 * @class All forms in the right content panel should have closeable jQuery UI style titles.
+	 * @name ss.contentPanel.form
 	 */
-	$('#contentPanel form').concrete('ss', function($){return{
+	$('#contentPanel form').concrete('ss', function($){return
+		/** @lends ss.contentPanel.form */
+		{
 		onmatch: function() {
 		  // Style as title bar
 			this.find(':header:first').titlebar({
@@ -219,11 +246,14 @@ var ss_MainLayout;
 	}});
 	
 	/**
-	 * Control the site tree filter.
+	 * @class Control the site tree filter.
 	 * Toggles search form fields based on a dropdown selection,
 	 * similar to "Smart Search" criteria in iTunes.
+	 * @name ss.Form_SeachTreeForm
 	 */
-	$('#Form_SearchTreeForm').concrete('ss', function($) {return{
+	$('#Form_SearchTreeForm').concrete('ss', function($) {return
+		/** @lends ss.Form_SeachTreeForm */
+		{
 		
 		/**
 		 * @type DOMElement
@@ -268,6 +298,9 @@ var ss_MainLayout;
 			});
 		},
 		
+		/**
+		 * Filter tree based on selected criteria.
+		 */
 		_submitForm: function(e) {
 			var self = this;
 			var data = [];
diff --git a/javascript/LeftAndMain.js b/javascript/LeftAndMain.js
index 3db70908..57d8213e 100644
--- a/javascript/LeftAndMain.js
+++ b/javascript/LeftAndMain.js
@@ -1,19 +1,22 @@
 (function($) {
 
 	/**
-	 * Main LeftAndMain interface with some control
-	 * panel and an edit form.
+	 * Available Custom Events:
+	 * <ul>
+	 * <li>ajaxsubmit</li>
+	 * <li>validate</li>
+	 * <li>loadnewpage</li>
 	 * 
-	 * Events:
-	 * - beforeSave
-	 * - afterSave
-	 * - beforeValidate
-	 * - afterValidate
+	 * @class Main LeftAndMain interface with some control
+	 * panel and an edit form.
+	 * @name ss.LeftAndMain
 	 */
-	$('.LeftAndMain').concrete('ss', function($){return{
+	$('.LeftAndMain').concrete('ss', function($){return
+		/** @lends ss.EditMemberProfile */
+		{
 		
 		/**
-		 *
+		 * @type Number
 		 */
 		PingIntervalSeconds: 5*60,
 		
@@ -76,26 +79,19 @@
 	}});
 	
 	/**
-	 * Base edit form, provides ajaxified saving
+	 * @class Base edit form, provides ajaxified saving
 	 * and reloading itself through the ajax return values.
 	 * Takes care of resizing tabsets within the layout container.
+	 * @name ss.Form_EditForm
 	 */
-	$('#Form_EditForm').concrete('ss',function($){return{	
-		onmatch: function() {
-			var self = this;
-			
-			// artificially delay the resize event 200ms
-			// to avoid overlapping height changes in different onresize() methods
-			$(window).resize(function () {
-				var timerID = "timerLeftAndMainResize";
-				if (window[timerID]) clearTimeout(window[timerID]);
-				window[timerID] = setTimeout(function() {self._resizeChildren();}, 200);
-			});
+	$('#Form_EditForm').concrete('ss',function($){return
+		/** @lends ss.Form_EditForm */
+		{	
 		
-			// trigger resize whenever new tabs are shown
-			// @todo This is called multiple times when tabs are loaded
-			this.find('.ss-tabset').bind('tabsshow', function() {self._resizeChildren();});
-		},
+		/**
+		 * @type String HTML text to show when the form has been deleted.
+		 */
+		RemoveHtml: null,
 		
 		/**
 		 * Suppress submission unless it is handled through ajaxSubmit()
@@ -158,7 +154,9 @@
 		 * Hook in (optional) validation routines.
 		 * Currently clientside validation is not supported out of the box in the CMS.
 		 * 
-		 * @return boolean
+		 * @todo Placeholder implementation
+		 * 
+		 * @return {boolean}
 		 */
 		validate: function() {
 			this.trigger('beforeValidate');
@@ -194,30 +192,41 @@
 
 			Behaviour.apply(); // refreshes ComplexTableField
 			
-			// If there's a title field and it's got a "new XX" value, focus/select that first
-			// This is really a little too CMS-specific (as opposed to LeftAndMain), but the cleanup can happen after jQuery refactoring
-			if($('input#Form_EditForm_Title') && $('input#Form_EditForm_Title').value.match(/^new/i)) {
-	    		$('input#Form_EditForm_Title').select();
-			}
+			// focus input on first form element
+			this.find(':input:visible:first').focus();
+			
+			this.trigger('loadnewpage', {response: response});
 		}
 	}});
 	
 	/**
-	 * All buttons in the right CMS form go through here by default.
+	 * @class All buttons in the right CMS form go through here by default.
 	 * We need this onclick overloading because we can't get to the
 	 * clicked button from a form.onsubmit event.
+	 * @name ss.Form_EditForm.Actions.submit
 	 */
-	$('#Form_EditForm .Actions :submit').concrete('ss', function($){return{
+	$('#Form_EditForm .Actions :submit').concrete('ss', function($){return
+		/** @lends ss.Form_EditForm.Actions.submit */
+		{
 		onclick: function(e) {
 			$(this[0].form).ajaxSubmit(this);
 			return false;
 		}
 	}});
 	
-	$('#TreeActions').concrete('ss', function($){return{
+	/**
+	 * @class Container for tree actions like "create", "search", etc.
+	 * @name ss.TreeActions
+	 */
+	$('#TreeActions').concrete('ss', function($){return
+		/** @lends ss.TreeActions */
+		{
+			
+		/**
+		 * Setup "create", "search", "batch actions" layers above tree.
+		 * All tab contents are closed by default.
+		 */
 		onmatch: function() {
-			// Setup "create", "search", "batch actions" layers above tree.
-			// All tab contents are closed by default.
 			this.tabs({
 				collapsible: true,
 				selected: parseInt(jQuery.cookie('ui-tabs-TreeActions')) || null,
@@ -227,10 +236,13 @@
 	}});
 	
 	/**
-	 * Link for editing the profile for a logged-in member
+	 * @class Link for editing the profile for a logged-in member
 	 * through a modal dialog.
+	 * @name ss.EditMemberProfile
 	 */
-	$('a#EditMemberProfile').concrete('ss', function($){return{
+	$('a#EditMemberProfile').concrete('ss', function($){return
+		/** @lends ss.EditMemberProfile */
+		{
 		
 		onmatch: function() {
 			var self = this;